swagger: '2.0' info: version: 1.0.142 x-ibm-name: ibm-watson-content-hub-api title: Acoustic Content API description: 'Copyright © Acoustic, L.P. 2023' schemes: - https consumes: - application/json produces: - application/json tags: - name: Authoring assets description: >- ## General Use the Content Asset service Rest APIs to work with assets. Assets are file types that are uploaded or created such as an image file, video file, or text that are used in content items. You can create, retrieve, update, and delete assets in a database. Managed assets are those located in the root dxdam directory as specified by its path and are visible on the Content UI. ## Content workflow (status) The status of a content item can be determined by the **suffix** of the ID: - An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix. - An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job. - An ID like xxxx with no suffix indicates that the content is **published** or **retired**. A draft can be created from published. When such a draft is published, it will override the previously published content. **Key notes:** - The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item. - Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published. - API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used. - Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published. - Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version. - name: Authoring categories description: >- Use the Acoustic Content category authoring data service Rest APIs to work with category and taxonomy items. - name: Authoring changes description: >- Use the Content Authoring Changes Rest APIs to apply changes, including bulk actions, to multiple types of Content items. - name: Authoring comments description: >- Use the Content Authoring comment APIs to work with comments. Comments are a simple way to associate a message to an item in Content. Comments are associated with a single item and user (creatorId). An item can have many comments. You can create, retrieve, and delete comments from a database. - name: Authoring content description: >2- ## General Use the Content content authoring data service Rest APIs to work with content documents. Content includes items that you compose in your content hub and upload from outside your content subscription. You can create, retrieve, and update content documents in a database. You can also create draft versions, change the status, and get a count of the total content in your database. ## Content workflow (status) The status of a content item can be determined by the **suffix** of the ID: - An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix. - An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job. - An ID like xxxx with no suffix indicates that the content is **published** or **retired**. A draft can be created from published. When such a draft is published, it will override the previously published content. **Key notes:** - The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item. - Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published. - API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used. - A draft item has a property ***linkedDocId***. This property is the ID the draft item will have when published. - Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version. - name: Authoring Import description: Provides generic copying and importing functionality - name: Authoring layouts description: > Use the Content content authoring layout service Rest APIs to work with layouts and layout mappings. Layouts define the template for the type documents. They define the markup and how to add content properties and elements into the markup. For example, the layouts 'Article', and 'Event' would define what an article or event looks like on the web site, or email. Layout Mappings define an association between a content-type and one or more layouts. Specifically marking those layouts as valid for the given content-type. - name: Authoring library description: >- Use the Content library Rest APIs to work with libraries. Libraries currently support having content and asset items added to them. - name: Authoring reference description: >- The Content Authoring reference API is used to retrieve information about references between items in the system. The type of relationships that are tracked depends on the type of item. Typically, if an item has an editable property that points to an ID of another item, it is tracked. You can use the API to fetch both incoming and outgoing references for any item. - name: Authoring renditions description: >- Use the Content renditions data service Rest APIs to work with image renditions. A 'rendition' of an image defines how you can customize a source image such as the width and height to be shown for a particular device or context. Renditions that are not referenced by an asset or content will be cleaned up periodically. - name: Authoring image profiles description: >- Use the Acoustic Content authoring image profile service Rest APIs to work with image profiles. You can create, retrieve, and update image profiles in a database. - name: Authoring resources description: >- Use the Content resources data service Rest APIs to work with resources. Resources are binary files that are stored in the CMS and used in content or site design. Resources that are not referenced by an asset or content will be cleaned up periodically. - name: Authoring review description: >- Use the Content Review Rest APIs to review assets and content. Use reviews to receive feedback from other members of your team. You can start, update, and complete the reviews that are set up. You can approve the content and assets under review. - name: Authoring search description: >2 ## General Use the Content authoring search service REST API to access assets, categories, content, content types, image profiles, and taxonomies by searching the content hub. You need prior authentication to use the authoring search service. The authoring search service contains content in all states including draft, ready, and retired. ## Content workflow (status) The status of a content item can be determined by the **suffix** of the ID: - An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix. - An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job. - An ID like xxxx with no suffix indicates that the content is **published** or **retired**. A draft can be created from published. When such a draft is published, it will override the previously published content. **Key notes:** - The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item. - Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published. - name: Authoring sites description: > Use the Content authoring sites service Rest APIs to work with sites. Sites are comprised of a site metadata and a hierarchy of pages. You can retrieve or update site metadata and create, read, update, and delete site pages belonging to a site. The out-of-the-box site has an ID of 'default'. - name: Authoring types description: > Use the Acoustic Content authoring type service Rest APIs to work with content type documents. Content types define a set of related elements that are used to create content. You can create, retrieve, and update content type documents in a database. You can also validate documents. Note: Documents created or updated in the old 1.0 format will be migrated to the 1.1 format on save. - name: Authoring version description: >- Use the Content version Rest APIs to work with authoring items that have versions. Versioned documents currently includes assets and content items within Content. The version APIs allow you to retrieve versions. - name: Authoring context search description: > The Authoring context search is a discretional middleware service that is positioned before the Search service. Use the Authoring context search Rest APIs to retrieve user targeted content items. You can target specific content items by providing the condition requests as filters. The filters that are currently supported by the API are 1. `accept-language` : Use this filter to target content items in a language of your preference. 2. `location` : Use this filter to target content items that are available in a location, that is, proximity to current location (within `distance` radius) of your preference. 3. `similar` : Use this filter to target content items or assets that are similar to a specified item. - name: Delivery context search description: > The Delivery context search is a discretional middleware service that is positioned before the Search service. Use the Delivery context search Rest APIs to retrieve user targeted content items. You can target specific content items by providing the condition requests as filters. The filters that are currently supported by the API are 1. `accept-language` : Use this filter to target content items in a language of your preference. 2. `location` : Use this filter to target content items that are available in a location, that is, proximity to current location (within `distance` radius) of your preference. 3. `similar` : Use this filter to target content items or assets that are similar to a specified item. - name: Delivery content description: > Use the Content delivery content service REST API to retrieve published content items. You can use the /delivery/v1/content routes to access content items as an unauthenticated user or the /mydelivery/v1/content routes to access content items including restricted ones as an authenticated user. While access to the latter routes requires at least Viewer role, accessing the anonymous routes does not require any authentication. You can retrieve a single content item by its ID or retrieve a collection of content items by passing in an array of IDs. You can also give one or more field names to these APIs so that only those fields (if they exist) are returned. To access draft content items you need to access the system in preview mode. For more information on the preview mode and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content. - name: Delivery render description: > The Content Delivery rendering REST API provides information to render content and pages in client-side applications. **Client-side programming support** If you want to create a client-side application with Angular 4, you can use the [Acoustic Angular SDK for Content](https://www.npmjs.com/package/@acoustic-content-sdk/ng-api). With the Angular SDK, you can retrieve and render content and pages from Content without any need to interact with the REST API directly. **Conditional GET requests** The API supports ETag and Last-modified [conditional GET requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests). It is highly recommended to use conditional GET requests with ETags to decrease the communication data between client and API. The API provides ETag and Last-modified header response information if available. The client can send conditional GET requests with ETag and Last-modified information to validate local client data. The API responds with a `304 - Not modified response` with empty content if the condition is still valid. **JSONP support** The API has [JSONP support](https://www.w3schools.com/js/js_json_jsonp.asp). The client can activate the JSONP support by providing the JSONP callback name query parameter. **Preview support** The API supports the previewing of content information as described [here](https://developer.goacoustic.com/acoustic-content/docs/preview-content). **Usage** In order to render content and the page structure in client-side applications you must to consider the following aspects: * Identify the addressed page that correlates to the application routing state. * Identify the addressed content and layout information and render the content. With the following steps you can achieve these aspects: 1. Retrieve the site and page information by using the "Delivery Site By ID" API route. The response contains information to identify the page that correlates to the navigational state (route) of the application. 2. The page information has the property "contentId" that references the content of the page. Use that property to get the content ID. 3. Use the content ID in combination with the "Delivery Rendering Context By ID" API route to retrieve the rendering context information of the content item. The rendering context contains the layout information of the content item and content references, including the resolved rendering context of the referenced items. 4. Based on the provided layout information, identify the related the layout component of your application and render the content item by using the layout component. If required the layout can render nested layouts. - name: Delivery resources description: > The Delivery Resource Service (DRS) provides access to the published resources in Akamai. The recommended URL for addressing published resources is the Akamai URL which is a static file access. For more information see [here](https://developer.goacoustic.com/acoustic-content/docs/publishing-and-delivering-content). You can use the /delivery/v1/resources routes to access resources as an unauthenticated user or the /mydelivery/v1/resources routes to access resources including restricted ones as an authenticated user. While access to the latter routes requires at least Viewer role, accessing the anonymous routes does not require any authentication. To access draft resources you need to access the system in preview mode. For more information on the preview mode and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content. - name: Delivery search description: >- Use the Content delivery search REST API to search for published assets, content items, categories and pages. You can use the /delivery/v1/search route to perform anonymous searches or the /mydelivery/v1/search route to perform authenticated searches that include restricted items. While access to the latter route requires at least Authenticated visitor role, accessing the anonymous route does not require any authentication. The delivery search provides access to published items only. To include draft items into your search, you can access this delivery search via the preview host. For more information on the preview host and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content - name: Delivery sites description: > Use the Content delivery sites service Rest APIs to retrieve published site artefacts. - name: Tenant Registry - name: Login service description: Login service offers endpoint to login into Acoustic Content. - name: Administering user profiles - name: Webhook profiles description: > Use the Content webhook service Rest APIs to work with webhook profiles. You can create, retrieve and update webhook profiles in a database. ### Webhook Timeouts and Retry policy Webhooks will automatically timeout (with no retry) after 5s which means that receivers should always perform their processing in background threads. The only situation whereby webhooks will be retried/re-sent is in the event of a communication error, and in this case only a single retry will occur. Note: Non-2xx responses from receivers are explicitly not retried - name: Publishing description: >- Use the Content Publishing APIs to update the default site revision, which is a snapshot of your published site at a specific time. current-job instance is used to track the state of the job. A site revision represents a specific revision of a site. parameters: commitTime16: name: commitTime in: query description: commit time for indexing - default is 60 000 (ms) required: false type: number format: int softCommit16: name: softCommit in: query description: do a soft commit right after indexing - default is true required: false type: boolean documents16: name: documents in: body description: the list of documents to be added required: true schema: &ref_50 type: object properties: documents: type: array items: &ref_51 type: object required: - id properties: id: type: string description: Unique identifier for the document baseInclude18: &ref_235 name: include in: query description: > Specify additional fields to include with each result. Valid options are: * links: Adds the 'links' section (see '#/definitions/DocumentLinks') to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both the fields that are specified in the 'fields' option and the fields in the 'include' option are returned. required: false type: string getInclude18: &ref_237 name: include in: query description: > Specify additional fields to include with each result. Valid options are: * links: Adds the 'links' section (see '#/definitions/DocumentLinks') to the response. * metadata: Adds additional details such as creator and last modifier to the response. * schema: Adds the 'schema' section to the response. * mappings: Add the 'mappings' section to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both the fields that are specified in the 'fields' option and the fields in the 'include' option are returned. required: false type: string updateOptions18: &ref_239 name: options in: query description: | Specify additional update directives. Valid directives are: * rebuild-path-filename: Instructs the service to re-generate the last fragment of the specified document path, by converting the specified document name into a filesystem friendly filename. required: false type: string bulkRequest23: &ref_247 name: bulkRequest in: body description: >- The request object containing the list of ids to be looked up and the fields (optional) to be included in the response. schema: &ref_77 required: - ids properties: ids: &ref_78 type: array description: An array of ids that should be retrieved by this bulk request. items: type: string fields: &ref_79 type: array description: An array of fields that should be returned by this bulk request. items: type: string required: true id23: &ref_252 name: id in: path description: The ID of the content item. type: string format: uuid required: true fields23: &ref_253 name: fields in: query description: >- Reduce the returned content item down to just the specified fields. Fields are specified by a comma seperated list of field names and should only be used once in the query string. To only retrieve `rev` and `last-modified` this parameter should look like `fields=rev,last-modified`. type: string items: type: string collectionFormat: csv required: false HeaderContentType23: &ref_248 name: Content-Type in: header description: 'Content type of the request body, should be ''application/json''.' type: string required: true HeaderIfNoneMatch23: &ref_254 name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false ContentTypeQueryParameter24: &ref_261 in: query name: contentType description: >- Specifies the content type to be set on the response. Default is text/html. type: string required: false LayoutIdQueryParameter24: &ref_260 in: query name: layoutId description: Provide the ID of the layout to be used to pre-render the resource. type: string required: false IDQueryParameter24: in: query name: id description: >- Provide the ID of the resource. Note that IDs are always the IDs of published item, even if a draft exists with a different ID. For a site, use `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. type: string required: true IDPathParameter24: &ref_259 in: path name: id description: >- Provide the ID of the resource. Note that IDs are always the IDs of published item, even if a draft exists with a different ID. For a site, use `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. type: string required: true FieldQueryParameter24: &ref_267 name: fq description: The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string QueryParameter24: &ref_266 name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: false type: string JSONPCallbackParameter24: &ref_262 name: callback description: >- Provide the JSONP callback name for JSONP support. The callback name must designate a javascript function that can be executed in the global scope. The argument will be the deserialized JSON object. in: query required: false type: string RenderingContextQueryParameter24: &ref_263 in: query name: rcParam description: >- By specifying query parameters with arbitrary names, but start with the prefix 'rc' or 'RC' (case insensitive), e.g., 'RcParam1', 'rcMy', you can provide custom parameters that will be added to the rendering context JSON under the $context.customParameters section. type: string required: false fileIdentifier25: &ref_273 name: fileIdentifier in: path description: > Provide the resource Id of the resource to be retrieved. Optionally, if the extension (e.g. .jpg) is known then it can be appended to the id. type: string required: true path25: &ref_269 name: path in: query description: Provide the absolute path of the resource (URL encoded). type: string required: true commitTime26: name: commitTime in: query description: Commit time for indexing - default is 60 000 (ms) required: false type: number format: int softCommit26: name: softCommit in: query description: Do a soft commit right after indexing - default is true required: false type: boolean documents26: name: documents in: body description: The list of documents to be added required: true schema: &ref_86 type: object properties: documents: type: array items: &ref_87 type: object required: - id properties: id: type: string description: Unique identifier for the document HeaderAuthCookie41: &ref_285 x-ibm-dx-user-auth: private in: header name: x-ibm-dx-user-auth description: JWT encrypted user context set by login process required: false type: string HeaderDataCenter41: x-ibm-dx-dc-mapping-key: private in: header name: x-ibm-dx-dc-mapping-key description: >- The data center for the replication mapping (if missing -> performance impact) required: false type: string id41: &ref_295 in: path name: id description: The unique internal identifier of the entity that should be processed required: true type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' externalId41: &ref_288 in: query name: external-id description: The unique external identifier of the user (e.g. BlueID). required: false type: string format: email maxLength: 512 offset41: &ref_290 name: offset in: query description: The index of the first item to be included in the response required: false default: 0 minimum: 0 type: integer format: int32 limit41: &ref_291 name: limit in: query description: The maximum number of items to be included in the response required: false default: 10 minimum: 1 maximum: 10000 type: integer format: int32 startkey41: name: startkey in: query description: The start position of items to be included in the response required: false type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' endkey41: name: endkey in: query description: The start position of items to be included in the response required: false type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' privacyNotice41: &ref_289 name: privacy-notice in: query description: Parameter which must be set if the users privacy notice should be returned required: false type: boolean default: false include41: &ref_292 name: include in: query description: Include additional information sections required: false type: array items: type: string enum: - links - none expand4JobDefinition47: name: expand in: query description: Expand (inline) given references required: false type: array items: type: string enum: - source - profile - '*' - all include47: &ref_303 name: include in: query description: >- Optional include parameter. Currently the links section can be included using the value 'links'. required: false type: array items: type: string enum: - links - none offset47: name: offset in: query description: The index of the first item to be included in the response required: false default: 0 minimum: 0 type: integer format: int32 limit47: name: limit in: query description: The maximum number of items to be included in the response required: false default: 10 minimum: 0 maximum: 100 type: integer format: int32 id47: name: id in: path description: The ID of the item required: true type: string maxLength: 64 classification47: name: classification in: path description: The classification of the item required: true type: string enum: - asset - content - page - site - category - taxonomy force47: name: force in: query description: >- Force option which allows to enforce an operation regardless of the state of the addressed entity. required: false default: false type: boolean state47: name: state in: query description: Only jobs that have (one of) the specified state(s) will be returned required: false collectionFormat: multi type: array items: type: string enum: - ON_HOLD - WAITING - RUNNING - SUCCEEDED - CANCELLED - FAILED - ABORTED - VIRTUAL responses: UnexpectedError0: &ref_164 description: Unexpected error. schema: &ref_0 type: object description: an error response. properties: requestId: type: string description: The current request ID example: d64dc285-0b62-aaa3-841f-de3588b64d34 service: type: string description: The name of the service that produced the error example: authoring-resource requestMethod: type: string description: The Http method type of the current request example: GET requestUri: type: string description: The request uri example: /authoring/v1/assets errors: type: array items: &ref_7 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key example: error.asset.1 message: type: string description: The error message example: The id requested does not exist. description: type: string description: Optional detailed error message example: >- Please check the ID you provided is correct before retrying the request. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. locale: type: string description: The current locale used to produce the error message. example: en required: - code - key - message - description - category - level - parameters - locale required: - requestId - service - requestMethod - requestUri - errors DataStoreUnavailable0: &ref_163 description: Connection failed to data store. schema: *ref_0 UnexpectedError4: &ref_176 description: Unexpected error. schema: &ref_13 type: object description: An error response. properties: requestId: type: string description: The current request ID example: d64dc285-0b62-aaa3-841f-de3588b64d34 service: type: string description: The name of the service that produced the error example: authoring-resource requestMethod: type: string description: The Http method type of the current request example: GET requestUri: type: string description: The request uri example: /authoring/v1/comments errors: type: array items: &ref_14 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key example: error.comments.1000 message: type: string description: The error message example: The id requested does not exist. description: type: string description: Optional detailed error message example: >- Please check the ID you provided is correct before retrying the request. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. locale: type: string description: The current locale used to produce the error message. example: en required: - code - key - message - description - category - level - parameters - locale required: - requestId - service - requestMethod - requestUri - errors UnexpectedError12: &ref_208 description: Unexpected error. schema: &ref_1 type: object description: an error response. properties: requestId: type: string description: The current request ID example: d64dc285-0b62-aaa3-841f-de3588b64d34 service: type: string description: The name of the service that produced the error example: authoring-rendition requestMethod: type: string description: The Http method type of the current request example: GET requestUri: type: string description: The request uri example: /authoring/v1/renditions errors: type: array items: &ref_38 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key example: error.rendition.1 message: type: string description: The error message example: The id requested does not exist. description: type: string description: Optional detailed error message example: >- Please check the ID you provided is correct before retrying the request. more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. locale: type: string description: The current locale used to produce the error message. example: en required: - code - key - message - description - more_info - category - level - parameters - locale required: - requestId - service - requestMethod - requestUri - errors DataStoreUnavailable12: &ref_207 description: Connection failed to datastore. schema: *ref_1 UnexpectedError14: &ref_214 description: Unexpected error. schema: &ref_2 type: object description: an error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The Http method type of the current request requestUri: type: string description: The request uri errors: type: array items: &ref_42 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - locale required: - requestId - service - requestMethod - requestUri - errors DataStoreUnavailable14: &ref_213 description: Connection failed to data store. schema: *ref_2 BulkGetSuccess23: &ref_249 description: Success schema: &ref_80 type: array description: An array of JSON objects that contain the requested content items. items: &ref_3 title: Content type: object properties: id: type: string description: The ID of the content item. name: type: string description: The name of the content item. description: type: string description: The description text for this content item. classification: type: string description: >- The classification defines the document type. For content items, all documents are classified as "content". typeId: type: string description: The ID of the content type this item belongs to. locale: type: string description: 'locale of the document (e.g "en", or "de").' lastModified: type: string format: date-time description: >- The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: >- name of user for now, this property may change once user management is defined. created: type: string format: date-time description: >- The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: The Id of the user that created this content item. tags: type: array items: type: string uniqueItems: true description: The tags which has been set for this content item. elements: type: object description: >- Defined by the type and capture in the schema given by the type, in a real content, this property will be filled with more information. kind: type: array items: type: string uniqueItems: true description: The tags which has been set by AI. type: type: string description: >- This is the Id of the content type document this content is based on. examples: application/json: - id: f54e763a-fd53-424b-8ad9-7cc690cca2db name: demo-article description: first edited at 10/10/2017 classification: content typeId: 24490027-e55b-4739-a5a9-5c091c5d4a72 locale: en lastModified: '2017-10-10T11:43:26.720Z' lastModifierId: 8b7c9180-aefb-4114-b62a-77b040111557 created: '2017-10-10T11:38:25.023Z' creatorId: 8b7c9180-aefb-4114-b62a-77b040111557 tags: - 'user:Acoustic' - 'user:sample' keywords: [] status: ready elements: summary: elementType: text value: Describes title: elementType: text value: A demo article body: elementType: text value: >- This is a sample article about content that is managed by Content. author: elementType: text value: alan@mycompany.com category: elementType: category categoryIds: - ea8ba30b49d21dc79d559b73fd77b8c1 - 911cf1415a408d9655659d01d34d04a1 categories: - Sample Article/Tech - Sample Article/Example image: elementType: image renditions: default: renditionId: >- r=d7a1a2b9-47e4-4131-9c3c-18c464e84e68&a=98f98b21-fd87-4ca1-b98f-2dd9effe0d29 source: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG thumbnail: renditionId: 83408464-75e8-4027-b920-31f415e363ab source: >- /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68?resize=800px:600px&crop=800:500;0,50 width: 800 height: 500 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG?resize=800px%3A600px&crop=800%3A500%3B0%2C50 asset: id: 98f98b21-fd87-4ca1-b98f-2dd9effe0d29 resourceUri: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 fileName: SampleImage.JPG fileSize: 2059999 mediaType: image/jpeg width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG kind: [] type: Sample Article - id: 7f2335cc-d91d-4f52-9e26-2d9402e463c0 name: other-demo description: first edited at 10/9/2017 classification: content typeId: 24490027-e55b-4739-a5a9-5c091c5d4a72 locale: en lastModified: '2017-10-10T11:43:26.720Z' lastModifierId: 8b7c9180-aefb-4114-b62a-77b040111557 created: '2017-10-10T11:38:25.023Z' creatorId: 8b7c9180-aefb-4114-b62a-77b040111557 tags: - 'user:Acoustic' - 'user:sample' keywords: [] status: ready elements: summary: elementType: text value: Describes title: elementType: text value: A second article body: elementType: text value: This article is a second example for WCH author: elementType: text value: alan@mycompany.com category: elementType: category categoryIds: - ea8ba30b49d21dc79d559b73fd77b8c1 - 911cf1415a408d9655659d01d34d04a1 categories: - Sample Article/Tech - Sample Article/Example image: elementType: image renditions: default: renditionId: >- r=d7a1a2b9-47e4-4131-9c3c-18c464e84e68&a=98f98b21-fd87-4ca1-b98f-2dd9effe0d29 source: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG thumbnail: renditionId: 83408464-75e8-4027-b920-31f415e363ab source: >- /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68?resize=800px:600px&crop=800:500;0,50 width: 800 height: 500 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG?resize=800px%3A600px&crop=800%3A500%3B0%2C50 asset: id: 98f98b21-fd87-4ca1-b98f-2dd9effe0d29 resourceUri: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 fileName: SampleImage.JPG fileSize: 2059999 mediaType: image/jpeg width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG kind: [] type: Sample Article BulkBadRequest23: &ref_250 description: Bad request schema: &ref_4 type: object properties: service: type: string description: The name of the microservice that detected the error. requestId: type: string description: The ID of the request in which this error happened. errors: type: object description: This JSON object describes a specific error of an error condition. properties: code: type: integer description: >- An error code that is specific to the service that reports the error. message: type: string description: A brief error message. level: type: string enum: - WARNING - ERROR description: The error severity. description: type: string description: >- A detailed description that describes what caused the eror, and how to proceed. cause: type: object description: The causing error. locale: type: string description: The locale setting of the message and description text. examples: application/json: service: prod-delivery-content requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 2006 message: Content Id list cannot be empty. level: ERROR description: The content id list was not passed or was empty. locale: en GetByIdSuccess23: &ref_255 description: Success schema: *ref_3 headers: Etag: description: The Etag value identifies this content item for future requests. type: string examples: application/json: id: f54e763a-fd53-424b-8ad9-7cc690cca2db name: demo-article description: first edited at 10/10/2015 classification: content typeId: 24490027-e55b-4739-a5a9-5c091c5d4a72 locale: en lastModified: '2017-10-10T11:43:26.720Z' lastModifierId: 8b7c9180-aefb-4114-b62a-77b040111557 created: '2017-10-10T11:38:25.023Z' creatorId: 8b7c9180-aefb-4114-b62a-77b040111557 tags: - 'user:Acoustic' - 'user:sample' keywords: [] status: ready elements: summary: elementType: text value: Describes title: elementType: text value: A demo article body: elementType: text value: This is a sample article about content that is managed by Content. author: elementType: text value: alan@mycompany.com category: elementType: category categoryIds: - ea8ba30b49d21dc79d559b73fd77b8c1 - 911cf1415a408d9655659d01d34d04a1 categories: - Sample Article/Tech - Sample Article/Example image: elementType: image renditions: default: renditionId: >- r=d7a1a2b9-47e4-4131-9c3c-18c464e84e68&a=98f98b21-fd87-4ca1-b98f-2dd9effe0d29 source: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG thumbnail: renditionId: 83408464-75e8-4027-b920-31f415e363ab source: >- /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68?resize=800px:600px&crop=800:500;0,50 width: 800 height: 500 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG?resize=800px%3A600px&crop=800%3A500%3B0%2C50 asset: id: 98f98b21-fd87-4ca1-b98f-2dd9effe0d29 resourceUri: /delivery/v1/resources/d7a1a2b9-47e4-4131-9c3c-18c464e84e68 fileName: SampleImage.JPG fileSize: 2059999 mediaType: image/jpeg width: 4000 height: 3000 url: >- /b7e6dfb7-76cf-44a9-a354-2e212d4a878c/dxresources/d7a1/d7a1a2b9-47e4-4131-9c3c-18c464e84e68.JPG kind: [] type: Sample Article GetByIdBadRequest23: &ref_257 description: Bad request schema: *ref_4 examples: application/json: service: prod-delivery-content requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 2001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en ItemNotFound23: &ref_258 description: Not found schema: *ref_4 examples: application/json: service: prod-delivery-content requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 2003 message: 'Content not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A content item with the specified id was not found in the system. locale: en NotModified23: &ref_256 description: >- Not modified is returned when the If-None-Match header is used and the Etag value matches the most recent version of the response. UnexpectedError23: &ref_251 description: Unexpected error schema: *ref_4 examples: application/json: service: prod-delivery-content requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en GetResourceSuccess25: &ref_270 description: The requested resource. schema: type: string format: binary headers: Content-Type: description: Media type of resource. type: string GetByPathNotFound25: &ref_271 description: Not found schema: &ref_5 type: object properties: service: type: string description: Service name. requestId: type: string description: Request ID. errors: type: object properties: code: type: integer message: type: string level: type: string description: type: string locale: type: string examples: application/json: service: prod-delivery-resource requestId: a0c938dd-ab79-4a7c-b124-5f8bc57bb657 errors: code: 3003 message: 'Path not found: {path}.' level: ERROR description: The resource at the specified path could not be found. locale: en GetByIdNotFound25: &ref_274 description: Not found schema: *ref_5 examples: application/json: service: prod-delivery-resource requestId: a0c938dd-ab79-4a7c-b124-5f8bc57bb657 errors: code: 3009 message: 'File not found for resourceId: {resourceId}.' level: ERROR description: The resource with the specified resourceId could not be found. locale: en UnexpectedError25: &ref_272 description: Unexpected error schema: &ref_85 type: object properties: service: type: string description: Service name. requestId: type: string description: Request ID. errors: type: object properties: code: type: integer message: type: string level: type: string description: type: string locale: type: string examples: application/json: service: prod-delivery-resource requestId: a0c938dd-ab79-4a7c-b124-5f8bc57bb657 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en clientError47: &ref_301 description: Unable to handle the request as it does not match the API definition. schema: &ref_120 description: This JSON record represents an error condition. type: object properties: errors: type: array items: &ref_119 description: >- This JSON record represents an individual error or warning contained in an error message. type: object properties: code: type: integer description: An error code defined by the publishing service. message: type: string description: A message describing what went wrong. description: type: string description: >- Further explanation of the error condition and potential next steps to resolve the problem. more_info: type: string description: >- A URL pointing to a website that provides more information on the given error condition. level: type: string enum: - ERROR - WARNING description: The severity level of the message. Default is error. parameters: type: object description: >- Additional properties reflecting the dynamic parts of the error condition. cause: type: object description: >- This property can be used to transport causing error message records produced by a down-stream service calls. locale: type: string description: >- This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text. required: - code - message requestId: type: string description: The ID of the failing request. service: type: string description: The name of the service serving the error message. required: - errors - requestId definitions: Asset0: &ref_6 type: object properties: id: type: string description: The id of the asset. readOnly: true example: 0a800487f06d71eaf4cffdfde1ab28bc maxLength: 100 pattern: '^[a-zA-Z0-9*.\-_:]*$' rev: type: string description: The revision of the asset. readOnly: true pattern: '^[0-9]+-.*$' example: 2-c839bbb8844549c2e298275c4b2adcb8 name: type: string description: Name of the asset. classification: type: string readOnly: true enum: - asset description: The classification of the asset is always "asset". assetType: type: string readOnly: true description: The type of asset. Determined by the media type of the resource. enum: - image - video - file description: type: string description: Description of the asset. example: This is an image of a person. maxLength: 500 creatorId: type: string readOnly: true description: The ID of the user that created the asset. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e created: type: string format: date-time readOnly: true description: The date and time the asset was created. creator: type: string readOnly: true description: The name of the user who originally created the asset. lastModifierId: type: string readOnly: true description: The ID of the user that last modified the asset. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e lastModified: type: string format: date-time readOnly: true description: The date and time the asset was last modified. lastModifier: type: string readOnly: true description: The name of the user who last modified the item. systemModified: type: string format: date-time readOnly: true description: The date and time the asset was last modified by the system. fileName: type: string readOnly: true description: The file name of the asset's resource. example: hub.png fileSize: type: integer readOnly: true description: The size of the asset's resource in bytes. example: 123125 mediaType: type: string readOnly: true description: Media type of the asset's resource. example: image/png keywords: type: array readOnly: true items: type: string description: >- When AI analysis is complete, the document type assets will be automatically updated with keywords generated by the analysis. Keywords are updated only for PDF, doc, html, and plain text files. tags: title: Tags type: object description: >- The "values" array defines the user selected tags. The other two properties "declined" and "suggested" relate directly to the interaction with the cognitive analysis feature. properties: values: type: array description: >- Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them. items: type: string example: - 'faces:Lebron James' - sports - basketball declined: type: array description: >- This editable field is given for the store values from cogntivie analysis that the user has dismissed/rejected. This essentially. It is up to the API client to update this field. This field is not indexed for search. items: type: string suggested: readOnly: true description: >- Suggested field is a read only field that is populated if cognitive analysis is done on this asset. Once reviewed the suggestions can be cleared with a query parameter see update endpoint. The tags come in the form of "prefix:tag" e.g. "classification:sky" This field is not indexed for search. type: array items: type: string analysis: description: This field indicates the progress of AI analysis. readOnly: true type: string enum: - complete - failed - none - pending analysisStarted: description: >- This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began. type: integer readOnly: true required: - values - declined resource: type: string description: The ID of the uploaded resource this asset contains. example: 67c621ed48921b7338b84b4f415cba6b digest: type: string description: The Base64 encoded MD5 digest of the resouce the asset contains. example: 9jwWuI3TN+PhGfHcrSJHcQ== readOnly: true path: type: string pattern: '^/[\s\S]+[^/]$' maxLength: 650 description: >- The path to this asset, must begin with a leading slash. A unique constraint is placed on this path so that no other asset can have the same path. When updating path a collision results in error. Paths begining with "/dxdam/" are managed assets. example: /sales/images/hub.png categoryIds: type: array description: The IDs of the categories that define how this asset is categorized. items: type: string example: [] profiles: type: array description: The IDs of image profiles to add to use on this asset. items: type: string example: - 8b4698e3-6283-4bc5-9e1e-fff69c2b48be profileRenditions: type: array description: >- The transform instructions for each of the renditions in the "profiles" array. If a rendition for one of those image profiles is not defined, a rendition with the best fit will automatically be generated. items: title: Profile Rendition type: object properties: profileId: type: string description: >- The ID of the image profile this rendition belongs to. This ID must also be specified in the "profiles" array. profileName: type: string readOnly: true description: >- The name of the image profile this rendition belongs to. This field will only be included when metadata is provided as a value of the include query parameter. key: type: string description: The key to this rendition. label: type: string readOnly: true description: >- The label to this rendition. This field will only be included when metadata is provided as a value of the include query parameter. uri: type: string readOnly: true description: The URI to the resource in this rendition's dimensions. width: type: number readOnly: true description: The width defined for this rendition. height: type: number readOnly: true description: The height defined for this rendition. transform: title: Transform type: object description: >- The transform instructions to achieve this rendition's dimensions. If not specified, a best fit transformation will automatically be generated. properties: scale: type: number description: >- The scale to perform on the original resource. The value must be between 0 (exclusive) and 1 (inclusive). crop: title: Crop type: object description: >- The crop to apply on the resource after any scaling has been done. properties: x: type: number description: The X coordinate to start the crop from 'y': type: number description: The Y coordinate to start the crop from width: type: number description: The width to crop out height: type: number description: The height to crop out example: - profileId: a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86 profileName: Profile E key: renditionF label: Rendition F transform: scale: 0.0862 crop: x: 0 'y': 0 width: 10 height: 10 uri: >- /authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=10px:10px&crop=10:10;0,0 width: 10 height: 10 - profileId: a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86 profileName: Profile E key: renditionG label: Rendition G transform: scale: 0.17241 crop: x: 0 'y': 0 width: 20 height: 20 uri: >- /authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=20px:20px&crop=20:20;0,0 width: 20 height: 20 renditions: title: Renditions Metadata type: object description: >- The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset. properties: default: type: object properties: id: type: string readOnly: true description: The ID of the rendition. source: type: string readOnly: true description: The link to the rendition binary. status: type: string readOnly: true description: The workflow status of the asset. enum: - ready - draft - retired valid: type: boolean readOnly: true description: >- Boolean that indicates if an asset can be transitioned from draft to ready. Only available on draft assets. draftStatus: type: string description: >- This property shows the status of the draft and is only valid for draft items. By default, it is in-progress. default: in-progress enum: - in-review - in-progress - approved links: type: object title: Asset Links readOnly: true properties: self: type: object description: Relative link to the asset itself. readOnly: true properties: href: type: string readOnly: true example: >- /authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft media: type: object description: The link to the resource binary. readOnly: true properties: href: type: string readOnly: true example: /authoring/v1/resource/myResource.jpeg thumbnail: type: object description: >- The link to a thumbnail of the image. Only avaliable for certain assets of type image. readOnly: true properties: href: type: string readOnly: true example: >- /authoring/v1/resource/myResource.jpeg?fit=around|220:145&crop=220:145;*,* ready: type: object description: >- This link will appear for items that can be transitioned to the ready state. properties: href: type: string example: href: >- /authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/ready retire: type: object description: >- This link will appear for items that can be transitioned to the retired state. properties: href: type: string example: href: >- /authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/retire linkedDoc: type: object description: >- This link will appear if this item is a draft of an existing item. The link points to the primary item. properties: href: type: string example: href: /authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597 usageRights: title: Usage Rights type: object description: >- Usage rights are assigned to assets to help composers understand where and when an asset can be used. For example, an asset might be used only in print, only for an advertising campaign, and only for a limited time. properties: categories: type: array items: type: object properties: id: type: string description: The ID of the usage rights category associated to the asset. example: 00000000-0000-0000-0000-021000c8e20 path: type: string description: >- Name path of the usage rights category associated to the asset. This field will only be included when metadata is provided as a value of the include query parameter. example: Usage rights/Rights managed/Usage realm/Advertising expiration: type: string format: date-time description: >- The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset. example: '2017-08-28T14:00:00Z' review: type: object description: Information and/or state about the review. properties: id: type: string description: ID of the review. example: 3356c048-96d0-4d8d-9afe-5e7ae47b127a name: type: string description: Name of the review. example: my review started: type: string format: date-time description: The ISO 8601 date-time that the review started. example: '2017-07-10T03:20:10Z' ends: type: string format: date-time description: The ISO 8601 date-time that the review is to be completed by. example: '2017-07-10T03:20:10Z' ended: type: string format: date-time description: The ISO 8601 date-time that the review actually finished on. example: '2017-07-12T19:40:10Z' ownerId: type: string additionalProperties: false required: - id - name - started - ownerId metadata: type: object description: Information extracted from an image asset's metadata. properties: width: type: integer description: Width of the image. readOnly: true example: 1000 height: type: integer description: Height of the image. readOnly: true example: 1000 camera: type: object description: >- Digital camera information extracted from the image asset's metadata. properties: make: type: string description: The manufacturer of the camera used to take the photo. readOnly: true example: NIKON CORPORATION model: type: string description: The model of the camera used to take the photo. readOnly: true example: NIKON D90 focalLength: type: integer description: The focal length of the lens used to take the photo. readOnly: true example: 35 shutterSpeed: type: string description: >- The shutter speed setting of the camera used to take the photo. readOnly: true example: 1/200 iso: type: integer description: The ISO setting of the camera used to take the photo. readOnly: true example: 100 aperture: type: integer description: The aperture of the lens used to take the photo. readOnly: true example: 8 coverage: type: string description: >- Scope of the image. Possible uses include a location or a time period. readOnly: true example: 1972- creator: type: string description: Creator of the image. readOnly: true example: Acoustic Date: type: string description: Creation date and time of the image. readOnly: true example: '2017-10-23T01:23:57Z' description: type: string description: Description of the image. readOnly: true example: The Acoustic logo. publisher: type: string description: Publisher of the image. readOnly: true example: Acoustic rights: type: string description: Rights information of the image. readOnly: true example: Acoustic source: type: string description: Source information of the image. readOnly: true example: Acoustic subject: type: array description: Topic(s) of the image. readOnly: true items: type: string example: - Acoustic - logo title: type: string description: Title of the image readOnly: true example: Acoustic Logo headline: type: string description: Headline of the image readOnly: true example: The Acoustic logo. cognitive: type: object description: Information extracted from the asset produced by cognitive analysis readOnly: true properties: classifications: type: array description: The classification suggested by cognitive analysis readOnly: true items: type: string example: - people - person - adult person faces: type: array description: Person's details. Image asset only readOnly: true items: type: object properties: name: type: string description: Name of person readOnly: true example: Brad Pitt gender: type: string description: Gender of person readOnly: true example: Male age: type: object description: Age range of person readOnly: true properties: minimum: type: integer description: Minimum age of person readOnly: true example: 35 maximum: type: integer description: Maximum age of person readOnly: true example: 44 colors: type: object description: Prominent colors from an image. Image asset only readOnly: true properties: vibrant: type: string example: '#c78061' readOnly: true muted: type: string readOnly: true example: '#ae7157' darkVibrant: type: string readOnly: true example: '#4c2c1c' darkMuted: type: string readOnly: true example: '#50453f' lightVibrant: type: string readOnly: true example: '#d4a185' lightMuted: type: string readOnly: true example: '#d4bcac' concepts: type: array description: Perform concept extraction operations from documents readOnly: true items: type: string example: - Want - Need - 2006 albums entities: type: string description: Perform entity extraction operations from documents readOnly: true example: people keywords: type: array description: Perform keyword extraction operations from documents readOnly: true items: type: string example: - new theme - document - video - cover page status: type: string description: This field indicates the progress of AI analysis readOnly: true enum: - complete - failed - none - pending isManaged: type: boolean readOnly: true description: >- This field indicates whether the asset is managed or not. An asset is considered managed only if its asset path starts with "dxdam". altText: type: string description: >- A text description of the asset, used when the asset itself is not available or not displayed. example: This is an image of the Acoustic logo. caption: type: string description: A caption of the asset image. example: Acoustic linkedDocId: type: string readOnly: true description: >- Provided on drafts of existing items. This is the ID of the primary item. example: b289c02e-2c61-4643-aba6-e6b4e94c76e3 categories: type: array items: type: string description: The taxonomy categories that the user has associated the asset to. example: banner isSystem: type: boolean description: >- Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic. default: false libraryId: type: string description: >- If this property is set it points to library id that the item is assigned to. required: - resource QueryResult0: &ref_162 type: object properties: limit: type: integer description: The page size. Set to 50 by default. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /asset?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /asset?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /asset?offset=0&limit=50 items: type: array items: *ref_6 required: - limit - offset - href - items ErrorResponse0: *ref_0 Error0: *ref_7 NewCategory1: &ref_167 type: object properties: name: type: string description: >- The name of the category. It can contain any character except for a forward slash (/). parent: type: string description: >- The ID of the parent category. A taxonomy will be created if this is omitted. description: type: string description: The description of the category. permanent: type: boolean description: >- Used to identify system categories, if true the category can not be deleted. isSystem: type: boolean description: >- Used to identify system categories, if true the category can not be deleted or updated by users hidden: type: boolean description: >- If true the category is hidden in the Shell, value is not returned if false. Default is false. firstClassFor: type: string description: >- Array of item classifications to which this taxonomy is enabled. Acceptable values "" and "imagesAndVideos", default "". By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed. tags: type: array items: type: string uniqueItems: true description: Array of tags. This field is applicable only for taxonomy. kind: type: array items: type: string uniqueItems: true description: Array of kinds for the taxonomy/category required: - name Category1: &ref_8 type: object properties: id: type: string description: The ID of category. rev: type: string description: The revision of category. name: type: string description: The name of the category. classification: type: string description: Either a Taxonomy or category. description: type: string description: A written representation of the category. creatorId: type: string description: The uuid of the user who created the category. permanent: type: boolean description: >- Used to identify system categories, if true the category can not be deleted. isSystem: type: boolean description: >- Used to identify system categories, if true the category can not be deleted or updated by users hidden: type: boolean description: >- If true the category is hidden in the Shell, value is not returned if false. Default is false. firstClassFor: type: string description: >- Array of item classifications to which this taxonomy is enabled. Acceptable values "" and "imagesAndVideos", default "". By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed. parent: type: string description: >- The ID of the parent category. This is only required if the classification is a CATEGORY. ancestorIds: type: array description: >- An array of IDs for each of the category's ancestor categories. The ID of this category is not included. items: type: string namePath: type: array description: >- An array of names for each of the category's ancestor categories, in addition to the name of this category. minItems: 1 items: type: string tags: type: array items: type: string uniqueItems: true description: Array of tags. This field is applicable only for taxonomy. kind: type: array items: type: string uniqueItems: true description: Array of kinds for the taxonomy/category links: type: object description: A set of links to related documents. properties: self: type: object properties: href: type: string taxonomy: type: object description: >- A link to this category's taxonomy. This will only be included if this category is not a taxonomy. properties: href: type: string parent: type: object description: >- A link to this category's parent. This will only be included if this category is not a taxonomy. properties: href: type: string lastModified: type: string format: date description: When the category was last modified in ISO 8601 format. created: type: string format: date description: When the category was created in ISO 8601 format. required: - id - rev - name - classification - namePath - links - created - lastModified QueryResult1: &ref_166 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v1/categories?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v1/categories?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v1/categories?offset=0&limit=50 items: type: array items: *ref_8 QueryResultV21: &ref_169 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v2/categories?depth=2&limit=10&offset=10 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v2/categories?depth=2&limit=2&offset=20 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v2/categories?depth=2&limit=2&offset=0 total_count: type: integer description: >- The total number of results (regardless of offset/limit values). Need to include 'total_count' in the query param 'fields' for this field to be calculated. items: type: array items: *ref_8 ErrorResponse1: &ref_168 type: object description: an error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The HTTP method type of the current request requestUri: type: string description: The request URI errors: type: array items: &ref_9 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end-user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error1: *ref_9 ProjectCreate2: type: object properties: name: type: string description: The name of the project. tags: type: array description: The list of tags describing the project. items: type: string uniqueItems: true schedule: type: object properties: id: type: string description: 'The associated publish schedule id, if any.' thumbnail: type: object properties: resourceId: type: string description: the id of an `authoring/v1/resource` item. required: - name BulkRequest2: &ref_170 type: object properties: ids: type: array items: type: object properties: id: type: string example: 579c2232-7398-4c8b-921d-3932bfc45d19 classification: enum: - asset - content example: content description: >- The classification of the item. Only Assets and Content currently have workflow status. rev: type: string example: 2-c39187c4e3c5a69fb6a2b989aaf48330 BulkRequestWithId2: &ref_173 type: object properties: ids: type: array items: type: object properties: id: type: string example: 579c2232-7398-4c8b-921d-3932bfc45d19 classification: enum: - asset - content example: content description: The classification of the item. required: - ids BulkMoveRequest2: &ref_174 type: object properties: ids: type: array items: type: object properties: id: type: string example: 579c2232-7398-4c8b-921d-3932bfc45d19 classification: enum: - asset - content example: content description: The classification of the item. libraryId: type: string example: 579c2232-7398-4c8b-921d-3932bfc45d19 description: Id of the destination library. required: - ids - libraryId BulkResponse2: &ref_171 type: object properties: status: type: string enum: - success - partial - failure description: Represents the success of the request. missing: type: array description: >- These are dependencies of items that were requested. The operation should be repeated with these items also included. The format of the ids is the `uid` format with the classification and id combined. example: - 'content:a' - 'content:b' items: type: string genericErrors: type: array description: >- These are items that failed for system are not actionable directly by the API user. They may indicate system errors and also dependent errors i.e. where the item failed because its dependency failed. The format of the ids is the `uid` format with the classification and id combined. example: - 'content:c' - 'content:d' items: type: string userErrors: type: array description: >- These are items that failed for breaking various rules that make the operation valid. These are the actionable errors. The format of the ids is the `uid` format with the classification and id combined. example: - 'content:e' - 'content:f' items: type: string successful: type: array description: >- Even when there are failures some items can succeed, this is the list of ids that succeeded. The format of the ids is the `uid` format with the classification and id combined. example: - 'content:g' - 'content:h' items: type: string messages: type: object additionalProperties: type: object properties: uid: type: string description: >- The unique id across content hub items. It is the classification and id combined. example: 'content:3e5eb750-fbde-49b9-8741-844722981219' id: type: string description: the id of the item. example: 3e5eb750-fbde-49b9-8741-844722981219 classification: type: string description: Classification of the item example: content key: type: string description: error key example: missing.dependencies.20200 code: type: integer description: error code example: 20200 parameters: description: >- Depending on the error type additional information is added here. type: object ErrorResponse2: &ref_172 type: object description: an error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The Http method type of the current request requestUri: type: string description: The request uri errors: type: array items: &ref_10 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error2: *ref_10 QueryResult2: type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v1/content?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v1/content?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v1/content?offset=0&limit=50 items: type: array items: &ref_11 type: object properties: name: type: string description: The name of the project. example: My Project id: type: string description: The ID of the project. example: 925d1454-167b-431b-a54c-6cbf0354398d rev: type: string description: The current revision of the document. example: 25-2ba981d0661c3129c31cc4993e569e3f lastModified: type: string format: date-time description: >- The last modified date of this project item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only. example: '2016-11-02T06:28:47Z' lastModifierId: type: string description: The ID of the user that last modified the project. example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9 lastModifier: type: string description: The display name of the user that last modified the project. example: Thomas Watson created: type: string format: date-time description: >- The created date of this project item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only. example: '2016-11-02T06:28:47Z' creatorId: type: string description: The ID of the creator of the project. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: The display name of the user that created the project. example: Thomas Watson classification: description: >- The classification defines the document type. For project items, all documents are classified as "project". enum: - project version: description: 'The API version of the project, set by system.' enum: - '1.0' status: type: string description: the status of the project. enum: - in-progress - publishing - published - failed example: in-progress targetDate: type: string format: date-time example: '2018-11-02T06:28:47Z' description: >- if a schedule is set the target date of the schedule. Not editable directly on the project. Either update the schedule or choose a different schedule. published: type: string format: date-time example: '2018-12-02T06:28:47Z' description: >- Date the project actually published, Only appears on `published` projects. tags: type: array description: The list of tags describing the project item. items: type: string uniqueItems: true schedule: type: object properties: id: type: string example: 25dcd045-3b4a-49dc-bb7d-82849977b9fe description: 'The associated publish schedule id, if any.' name: type: string example: Nightly site update description: The name of the schedule. thumbnail: type: object properties: resourceId: type: string example: b1660c62-8788-4f21-9c83-608c0289fb47 description: The id of an `authoring/v1/resource` item. href: type: string example: >- /authoring/v1/resources/b1660c62-8788-4f21-9c83-608c0289fb47?fit=inside%7C220:145 description: The url to the thumbnail of the specified resource. kind: type: array description: The type of project. items: type: string enum: - managed - publishing-job uniqueItems: true required: - name - tags Project2: *ref_11 ResponseComment4: &ref_12 type: object properties: creatorId: type: string description: The ID of the user that created the commment. example: f8c1344e-2296-441b-a8a6-f8d46b72a787 id: type: string description: The id of the comment. example: 95927bcd-9da3-4d8a-9fbf-ffcabe80a8a4 rev: type: string description: The revision of the comment. example: 2-c839bbb8844549c2e298275c4b2adcb8 message: type: string description: The actual comment message. example: More images should be added to slideshow created: type: string format: date-time description: ISO-8601 formatted date. example: '2017-05-28T22:59:27.610Z' target: type: object properties: id: type: string description: The id of the item that the comment is associated with. example: 6eac5498-3545-458a-962b-e17742aa7b56 classification: type: string description: >- The classification of the item that the comment is associated with. enum: - asset - content example: content required: - id - classification threadId: type: string description: The id string of the thread that this comment belongs to. example: b3a18c87-8be0-4938-bba9-98a4cea35200 classification: type: string description: The comment's classification. example: Comment kind: type: array description: >- The "kind" of comment that this is. By default, all comments created by users are "user" comments. default: - user items: type: string enum: - user - system creator: type: string description: Display name of the user who created this comment. example: Krista lastModifier: type: string description: The display name of the user who last edited the comment. example: Krista lastModifierId: type: string description: The ID of the user who last edited the comment. example: f8c1344e-2296-441b-a8a6-f8d46b72a787 lastModified: type: string description: The ISO-8601 timestamp that the comment was last modified. example: '2017-05-28T22:59:27.610Z' resolved: type: boolean default: false description: >- Used for resolving comments during a review. This property is false by default and changes to true when the comment is resolved. required: - id - rev - classification - created - creator - creatorId - kind - lastModified - lastModifier - lastModifierId - message - resolved - target - threadId NewComment4: &ref_175 type: object properties: message: type: string description: The actual comment message. example: More images should be added to slideshow target: type: object properties: id: type: string description: The id of the item that the comment is associated with. example: 6eac5498-3545-458a-962b-e17742aa7b56 classification: type: string description: >- The classification of the item that the comment is associated with. enum: - asset - content example: content required: - id - classification required: - message - target EditComment4: &ref_177 type: object properties: message: type: string description: The actual comment message. example: More images should be added to slideshow. required: - message QueryResult4: &ref_178 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /comments?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /comments?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /comments?offset=0&limit=50 items: type: array items: *ref_12 required: - limit - offset - href - items ErrorResponse4: *ref_13 Error4: *ref_14 Cognitive5: &ref_184 type: object properties: concepts: type: array items: type: string example: - news - sample entities: type: array items: type: object properties: name: type: string type: type: string Count5: &ref_183 type: object properties: count: type: integer example: count: 348 required: - count NewContent5: &ref_181 type: object properties: name: type: string description: The name of the content item. example: Sample Content typeId: type: string description: The ID of the content type this content item is based on. example: b0798e67-3da2-48b4-b044-016495fa3ead elements: type: object description: > Elements are defined in the content type. A content type for a content is referenced through the typeId attribute. The elements in the content are based on the content type that is referenced. A content can have multiple elements such as text, number, video, images. For example, to include a text element include \"someTextElement\":{\"elementType\": \"text\", \"value\": \"some text goes here\" }. For a complete list of content elements, see https://developer.goacoustic.com/acoustic-content/reference#authoring-content isSystem: type: boolean description: >- Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic. default: false libraryId: type: string description: >- If this property is set it points to library ID that the item is assigned to. required: - name - typeId Content5: &ref_15 title: Content Schema type: object properties: id: type: string description: The ID of the content item. example: 925d1454-167b-431b-a54c-6cbf0354398d rev: type: string description: The current revision of the document. example: 25-2ba981d0661c3129c31cc4993e569e3f name: type: string description: The name of the content item. example: Sample Content description: type: string description: The description of the content item. example: An example description of the sample content typeId: type: string description: The ID of the content type this item belongs to. example: b0798e67-3da2-48b4-b044-016495fa3ead type: type: string description: >- The name of the content type this item belongs to. Only included when using include=metadata example: Article kind: type: string description: >- The kind of the content. Recognized values are "site", "page", "landing-page", "email" example: email lastModified: type: string format: date-time description: >- The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read-only. example: '2016-11-02T06:28:47Z' lastModifierId: type: string description: The ID of the user that last modified the content. example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9 lastModifier: type: string description: The display name of the user that last modified the content. example: Thomas Watson created: type: string format: date-time description: >- The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read-only. example: '2016-11-02T06:28:47Z' creatorId: type: string description: The ID of the creator of the content. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: The display name of the user that created the content. example: Thomas Watson classification: description: >- The classification defines the document type. For content items, all documents are classified as "content". enum: - content status: description: the workflow status of the content. enum: - draft - ready - retired linkedDocId: type: string description: >- Provided on drafts of existing items. This is the ID of the primary item. example: b289c02e-2c61-4643-aba6-e6b4e94c76e3 elements: type: object description: >- The elements section is dependent on the content type of this content. (Referenced via the typeId attribute) with Elements are defined in the content type and therefore the elements section is dependent on the content type of this content. The content type is referenced through the typeId attribute. A content can have multiple elements such as text, number, video, images etc. For a complete list of content elements see, https://developer.goacoustic.com/acoustic-content/reference#authoring-content example: videokey: elementType: video asset: id: a21b3718-a801-4343-8a73-6f94ee2763ba resourceUri: /authoring/v1/resources/438259a6a8ac72817ee2b2a14078c4a1 fileSize: 448338 fileName: testVideo.mp4 mediaType: video/mp4 thumbnail: resourceId: ef2e1f5fa89f2f93dfba19520f629c84 resourceUri: /authoring/v1/resources/ef2e1f5fa89f2f93dfba19520f629c84 fileName: cap.jpg categorykey: elementType: category categoryIds: - ae607a10216249805ee0488d3e0f1e64 datekey: elementType: datetime value: '2016-11-07T10:09:00Z' textkey: elementType: text value: >- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua togglekey: elementType: toggle value: true linkkey: elementType: link linkURL: 'http://acoustic.com' linkText: Acoustic imagekey: elementType: image renditions: default: renditionId: 61096914-e33a-4021-9a5d-be06337206fd source: >- /authoring/v1/resources/c45c83a8-2738-48a2-89e1-35256ee16283.jpg asset: id: 400974f1-10d8-4db9-a711-a840e315fdef resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba4648d82 fileName: cap.jpg fileSize: 113730 mediaType: image/jpeg filekey: elementType: file asset: id: 913099e2-3e53-497c-b264-77ed974b1694 resourceUri: /authoring/v1/resources/a9a19a26209fed0b96612d6263618d9b fileSize: 145592 fileName: news.pdf mediaType: application/pdf numberkey: elementType: number value: 42 imagewithprofilekey: elementType: image renditions: default: renditionId: 39a94d18-9063-4785-80f8-cc5520255afe source: >- /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg mobile: renditionId: 583d4fa3-7b3f-4c31-8aca-f1a32e3f5d6b source: >- /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg?resize=0.16286644951140064xw:0.16286644951140064xh&crop=200:200;56,0 asset: id: b4703646-2ae9-4ef3-8d2d-9f8a2d5f2545 resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba464a0f9 fileName: tree-738816_1920.jpg fileSize: 273419 mediaType: image/jpeg tags: type: array description: The tags describing the content item. items: type: string uniqueItems: true example: - news - sample links: type: object properties: self: type: object description: The default link back to this document properties: href: type: string example: href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d linkedDoc: type: object description: >- This link will appear if this item is a draft of an existing item. The link points to the primary item properties: href: type: string example: href: /authoring/v1/content/fd95f9a53edd5c2ae4ebdf2ba464a0f9 draft: type: object description: >- This link will appear on an item if there exists a draft of this item. The link points to the draft. properties: href: type: string example: href: /authoring/v1/content/fd95f9a53edd5c2ae4ebdf2ba464a0f9 create-draft: type: object description: >- This link will appear for items in ready and retired state that don't already have an existing draft. It will create a draft of this item. properties: href: type: string example: href: >- /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/create-draft ready: type: object description: >- This link will appear for items that can be transitioned to the ready state. properties: href: type: string example: href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/ready retire: type: object description: >- This link will appear for items that can be transitioned to the retired state. properties: href: type: string example: href: >- /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/retire type: type: object description: This is the link to the content's type. properties: href: type: string example: href: /authoring/v1/types/b0798e67-3da2-48b4-b044-016495fa3ead thumbnail: type: object description: > The reference to the resource that should act as the thumbnail of this content item. The thumbnail can be referred to by either ID or path. This field is read-only, and is determined by the contentThumbnail field on the content type. The type can specify an image element on this content item, or a specific image resource. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: The path of the resource. example: /sales/images/hub.png url: type: string description: The URL of the resource. example: /authoring/v1/resources/47d535ff288b3bd8383009abf82a9ea8 isSystem: type: boolean description: >- Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic. default: false libraryId: type: string description: >- If this property is set it points to library ID that the item is assigned to. additionalProperties: false UpdateContent5: &ref_182 type: object properties: rev: type: string description: The current revision of the document. example: 25-2ba981d0661c3129c31cc4993e569e3f typeId: type: string description: The ID of the content type this content item is based on. example: b0798e67-3da2-48b4-b044-016495fa3ead QueryResult5: &ref_179 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v1/content?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v1/content?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v1/content?offset=0&limit=50 items: type: array items: *ref_15 BulkDelete5: type: object properties: ids: type: array items: type: string ErrorResponse5: &ref_180 type: object description: an error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The HTTP method type of the current request requestUri: type: string description: The request URI errors: type: array items: &ref_16 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end-user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error5: *ref_16 NewDefaultContent5: type: object properties: name: type: string description: The name of the default content item. example: Sample Default Content typeId: type: string description: The ID of the content type this default content item is based on. example: b0798e67-3da2-48b4-b044-016495fa3ead elements: type: object description: > Elements are defined in the content type. A content type for a default content is referenced through the typeId attribute. The elements in the default content are based on the content type that is referenced. A default content can have multiple elements such as text, number, video, images. For example, to include a text element include \"someTextElement\":{\"elementType\": \"text\", \"value\": \"some text goes here\" }. For a complete list of default content elements, see https://developer.goacoustic.com/acoustic-content/reference#authoring-content required: - name - typeId DefaultContent5: &ref_17 title: Default Content Schema type: object properties: id: type: string description: The ID of the default content item. example: 925d1454-167b-431b-a54c-6cbf0354398d rev: type: string description: The current revision of the document. example: 25-2ba981d0661c3129c31cc4993e569e3f name: type: string description: The name of the default content item. example: Sample Default Content description: type: string description: The description of the default content item. example: An example description of the sample default content typeId: type: string description: The ID of the content type this item belongs to. example: b0798e67-3da2-48b4-b044-016495fa3ead type: type: string description: >- The name of the content type this item belongs to. Only included when using include=metadata example: Article lastModified: type: string format: date-time description: >- The last modified date of this default content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read-only. example: '2016-11-02T06:28:47Z' lastModifierId: type: string description: The ID of the user that last modified the default content. example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9 lastModifier: type: string description: The display name of the user that last modified the default content. example: Thomas Watson created: type: string format: date-time description: >- The created date of this default content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read-only. example: '2016-11-02T06:28:47Z' creatorId: type: string description: The ID of the creator of the default content. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: The display name of the user that created the default content. example: Thomas Watson classification: description: >- The classification defines the document type. For default content items, all documents are classified as "default-content". enum: - default-content elements: type: object description: >- The elements section is dependent on the content type of this default content. (Referenced via the typeId attribute) with Elements are defined in the content type and therefore, the elements section is dependent on the content type of this content. The content type is referenced through the typeId attribute. A default content can have multiple elements such as text, number, video, images etc. For a complete list of default content elements see, https://developer.goacoustic.com/acoustic-content/reference#authoring-content example: videokey: elementType: video asset: id: a21b3718-a801-4343-8a73-6f94ee2763ba resourceUri: /authoring/v1/resources/438259a6a8ac72817ee2b2a14078c4a1 fileSize: 448338 fileName: testVideo.mp4 mediaType: video/mp4 thumbnail: resourceId: ef2e1f5fa89f2f93dfba19520f629c84 resourceUri: /authoring/v1/resources/ef2e1f5fa89f2f93dfba19520f629c84 fileName: cap.jpg categorykey: elementType: category categoryIds: - ae607a10216249805ee0488d3e0f1e64 datekey: elementType: datetime value: '2016-11-07T10:09:00Z' textkey: elementType: text value: >- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua togglekey: elementType: toggle value: true linkkey: elementType: link linkURL: 'http://acoustic.com' linkText: Acoustic imagekey: elementType: image renditions: default: renditionId: 61096914-e33a-4021-9a5d-be06337206fd source: >- /authoring/v1/resources/c45c83a8-2738-48a2-89e1-35256ee16283.jpg asset: id: 400974f1-10d8-4db9-a711-a840e315fdef resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba4648d82 fileName: cap.jpg fileSize: 113730 mediaType: image/jpeg filekey: elementType: file asset: id: 913099e2-3e53-497c-b264-77ed974b1694 resourceUri: /authoring/v1/resources/a9a19a26209fed0b96612d6263618d9b fileSize: 145592 fileName: news.pdf mediaType: application/pdf numberkey: elementType: number value: 42 imagewithprofilekey: elementType: image renditions: default: renditionId: 39a94d18-9063-4785-80f8-cc5520255afe source: >- /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg mobile: renditionId: 583d4fa3-7b3f-4c31-8aca-f1a32e3f5d6b source: >- /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg?resize=0.16286644951140064xw:0.16286644951140064xh&crop=200:200;56,0 asset: id: b4703646-2ae9-4ef3-8d2d-9f8a2d5f2545 resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba464a0f9 fileName: tree-738816_1920.jpg fileSize: 273419 mediaType: image/jpeg tags: type: array description: The tags describing the default content item. items: type: string uniqueItems: true example: - news - sample links: type: object properties: self: type: object description: The default link back to this document properties: href: type: string example: href: >- /authoring/v1/default-content/925d1454-167b-431b-a54c-6cbf0354398d type: type: object description: This is the link to the content's type. properties: href: type: string example: href: /authoring/v1/types/b0798e67-3da2-48b4-b044-016495fa3ead thumbnail: type: object description: > The reference to the asset that should act as the thumbnail of this default content item. The thumbnail can be referred to by either ID or path. This field is read-only, and is determined by the contentThumbnail field on the content type. The type can specify an image element on this default content item, or an image from a particular asset. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: The path of the asset. example: /sales/images/hub.png url: type: string description: The URL of the asset. example: /authoring/v1/resources/47d535ff288b3bd8383009abf82a9ea8 additionalProperties: false UpdateDefaultContent5: type: object properties: rev: type: string description: The current revision of the document. example: 25-2ba981d0661c3129c31cc4993e569e3f typeId: type: string description: The ID of the content type this default content item is based on. example: b0798e67-3da2-48b4-b044-016495fa3ead DefaultContentQueryResult5: type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v1/content?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v1/content?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v1/content?offset=0&limit=50 items: type: array items: *ref_17 ValidationResult5: &ref_185 type: object description: a validation response. properties: failedIds: type: array description: The submitted ID which failed validation. items: type: string description: The ID of the content item which failed validation example: b0798e67-3da2-48b4-b044-016495fa3ead messages: type: object description: The validation errors which occurred for the content item properties: SOME_ID: type: array description: The array of error messages for this id items: *ref_16 CopyBody7: &ref_186 type: array description: > The items to copy. The items need to be either ready OR belong to same project. Additional parameters "name", "add" and "remove" can be passed with each item to modify the name and add or remove a property from the copied item. Format is "[classification]:[id]?name=[custom-name];remove={\"kind\":[\"sample\"],\"description\":\"\"};add={\"kind\":[\"email\"]}" The above parameters mean that the (a) name of the copied item would be . (b) "email" will be added to the "kind" array in the copied object. (c) "sample" will be removed from "kind" array in the copied object. (d) "description" will be removed from the copied object. items: type: string example: - 'content:2fd35e68-b4d2-4608-8dbe-82c42b321bd9' - 'content:2fd35e68-b4d2-4608-8dbe-82c42b321bd9:draft' - 'content:2fd35e68-b4d2-4608-8dbe-82c42b321bd9?name=custom-name' - >- content:2fd35e68-b4d2-4608-8dbe-82c42b321bd9?name=mycontent;remove={"kind": ["sample"]};add={"kind":["email"] CopyResponse7: type: object description: An acknowledgement of the copy operation request. properties: jobId: type: string description: jobId to track the status of copy operation. example: jobId: 0c2ea21b-9640-4357-80ac-6e2053427f46 message: type: string description: A descriptive message. example: message: Copy in progress linkToStatus: type: string description: URI of the endpoint to track status of the copy operation. example: linkToStatus: /authoring/v1/copy/0c2ea21b-9640-4357-80ac-6e2053427f46 CopyRecord7: type: object description: a copy operation document. properties: id: type: string description: The ID of the associated copy operation. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 classification: type: string description: the document classification. enum: - copy created: type: string description: >- The creation of this document in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time lastModified: type: string description: >- The last modified date of this document in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 status: type: string description: the status of the copy operation. enum: - in-progress - success - partial-success - failed params: type: object description: Set of all passed/resolved query parameters example: referenceLevels: 1 referencesToClear: image-profile referencesToReplace: asset rootCopiedItemCount: type: integer description: The initial number of items requested to be copied. example: 5 nonrootCopiedItemCount: type: integer description: The number of referenced items that were copied. example: 50 followupCount: type: integer description: The number of items that require follow-up reference handling example: 10 failedToCopyCount: type: integer description: The number of items that failed to be copied example: 0 rootCopiedItemList: type: object description: > The list of initial items that have been copied. Not always available. Once this list grows greater than 100 items, then its offloaded to separate storage and hence not available (on this record) until the list size goes back to 0. The format is "[SOURCE-ITEM-CLASSIFICATION]:::[SOURCE-ITEM-ID]":"[COPY-ITEM-CLASSIFICATION]:::[COPY-ITEM-ID]" example: 'content:::item1-id': 'content:::item1-id-copy' 'content:::item2-id': 'content:::item2-id-copy' nonrootCopiedItemList: type: object description: > The list of referenced items that have been copied. Not always available. Once this list grows greater than 100 items, then its offloaded to separate storage and hence not available (on this record) until the list size goes back to 0. The format is "[SOURCE-ITEM-CLASSIFICATION]:::[SOURCE-ITEM-ID]":"[COPY-ITEM-CLASSIFICATION]:::[COPY-ITEM-ID]" example: 'content:::item1-id': 'content:::item1-id-copy' 'content:::item2-id': 'content:::item2-id-copy' followupList: type: object description: > The list of items that require follow-up reference handling. Not always available. Once this list grows greater than 100 items, then its offloaded to separate storage and hence not available (on this record) until the list size goes back to 0. The format is "[COPY-ITEM-CLASSIFICATION]:::[COPY-ITEM-ID]":"[IS-ROOT]:::[IS-CLEARING-ELEMENTS]" example: 'content:::item1-id-copy': 'false:::false' 'content:::item2-id-copy': 'true:::false' failedToCopyList: type: object description: > The list of items items that failed to be copied. Not always available. Once this list grows greater than 50 items, then its offloaded to separate storage and hence not available (on this record) until the list size goes back to 0. The format is "[SOURCE-ITEM-CLASSIFICATION]:::[SOURCE-ITEM-ID]":"[IS-ROOT]:::[IS-CLEARING-ELEMENTS]" example: 'content:::item3-id': 'false:::false' 'asset:::item4-id': 'true:::false' CopyResult7: &ref_187 type: object description: A copy operation result. properties: classification: type: string description: the document classification. enum: - copy status: type: string description: the status of the copy operation. enum: - success - failed params: type: object description: The list of query parameters applied for the copy operation. example: referenceLevels: '5' referencesToClone: content clearElementsOnLastLevel: 'false' rootCopiedItemCount: type: integer description: The number of root items copied in this request. rootCopiedItemList: type: object description: A mapping of all root source item ids to the copied item ids. example: 'content:::item1-id': 'content:::item1-id-copy' 'content:::item2-id': 'content:::item2-id-copy' nonrootCopiedItemCount: type: integer description: The number of non-root items copied in this request. nonrootCopiedItemList: type: object description: A mapping of all non-root source item ids to the copied item ids. example: 'content:::item1-id': 'content:::item1-id-copy' 'content:::item2-id': 'content:::item2-id-copy' failedToCopyCount: type: integer description: The number of source items for which the copy operation failed. failedToCopyList: type: object description: >- The list of failed source item ids to failure data. Failure data format is 'isRoot:::clearElements' example: 'content:::item1-id-copy': 'false:::false' 'content:::item2-id-copy': 'true:::false' ErrorResult7: &ref_188 type: object description: an error response. properties: errors: type: array items: &ref_18 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code. key: type: string description: The message key. message: type: string description: The error message. description: type: string description: Optional detailed error message. more_info: type: string description: Optional additional information for the message. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user. enum: - API - USER level: type: string description: Indicates the message level. enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. requestId: type: string description: The current request ID. service: type: string description: The name of the service that produced the error. requestMethod: type: string description: The Http method type of the current request. requestUri: type: string description: The current request uri. Message7: *ref_18 Count9: &ref_193 type: object properties: count: type: integer NewLayout9: &ref_189 type: object description: A new layout. properties: name: type: string description: The name of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 example: Sample layout description: type: string description: The description of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' example: An example description of the sample layout classification: type: string description: Indicates the type of this document. enum: - layout created: type: string description: >- Optional creation date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. Value is ignored if set in the future. format: date-time path: type: string description: >- Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myLayouts/SampleLayout.json prerender: type: boolean description: Indicates if the layout should be prerendered. default: false example: false tags: type: array items: type: string uniqueItems: true example: - news - sample thumbnail: type: object description: > The reference to the asset that should act as the thumbnail of this layout. The thumbnail can be referred to by either id or path. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: The path of the asset. example: /sales/images/hub.png template: type: string minLength: 1 example: /mytemplates/template.hbs templateType: type: string description: >- Specifies the type of template associated with this layout. This field is required when prerender field is set to true. enum: - handlebars - angular default: handlebars example: handlebars urlTemplate: type: string description: Specifies the pattern for url generation. isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - name - template NewLayoutMapping9: &ref_194 type: object description: A new layout mapping. properties: name: type: string description: The name of the layout mapping. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 example: Sample layout mapping classification: type: string description: Indicates the type of this document. enum: - layout-mapping created: type: string description: >- Optional creation date of this layout mapping in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. Value is ignored if set in the future. format: date-time path: type: string description: >- Optional path to associate with the layout mapping. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myLayoutMappings/SampleMapping.json tags: type: array items: type: string uniqueItems: true example: - news - sample type: &ref_20 type: object description: > The mapped content-type. Must be unique. During create and update operations, the mapped content-type can be referred to by either id or name. properties: id: type: string description: The ID of the mapped content-type. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 example: 092c46f6-09c0-4ffe-9f21-52d041b4a73c name: type: string description: > The name of the mapped content-type. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. example: Sample Type mappings: type: array description: The mapped layouts. items: &ref_21 type: object description: > an individual layout mapping entry. During creates and updates, if there is only one layout specified within the 'layouts' property, then the 'defaultLayout' property is optional (and will be inserted by the system). properties: defaultLayout: &ref_19 type: object description: an individual layout reference. properties: id: type: string description: The ID of the referenced layout. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 example: f26044ca-d92d-49e8-acd9-00563c1e0db9 name: type: string description: > The name of the referenced layout. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Sample Layout required: - id layouts: type: array description: >- The full set of layouts (including the default) associated with this entry. Only layouts specified in this list can be set as a Content override (via the Content.selectedLayouts property) items: *ref_19 minItems: 1 required: - defaultLayout - layouts minItems: 1 maxItems: 1 isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - name - type - mappings ExistingLayout9: &ref_22 type: object description: An existing layout. properties: id: type: string description: The ID of the layout. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 example: f26044ca-d92d-49e8-acd9-00563c1e0db9 rev: type: string description: The current revision of the layout. minLength: 1 example: 139c63397272172e73f52d22f22f606f6c name: type: string description: The name of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 example: Sample layout description: type: string description: The description of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' example: An example description of the sample layout classification: type: string description: Indicates the type of this document. enum: - layout creatorId: type: string description: The ID of the user that created the layout. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: > The display name of the user that created the layout. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson created: type: string description: >- The created date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time lastModifierId: type: string description: The ID of the user that last modified the layout. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f lastModifier: type: string description: > The display name of the last user that modified the layout. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson lastModified: type: string description: >- The last modified date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time path: type: string description: >- Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myLayouts/SampleLayout.json prerender: type: boolean description: Indicates if the layout should be prerendered. default: false example: false tags: type: array items: type: string uniqueItems: true example: - news - sample thumbnail: type: object description: > The reference to the asset that should act as the thumbnail of this layout. The thumbnail can be referred to by either id or path. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: > The path of the asset. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: /sales/images/hub.png url: type: string description: > The URL of the asset. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: /authoring/v1/resources/d45c83a8-2738-48a2-89e1-35256ee16283.jpg template: type: string minLength: 1 example: /mytemplates/template.hbs templateType: type: string description: >- Specifies the type of template associated with this layout. This field is required when prerender field is set to true. enum: - handlebars - angular default: handlebars example: handlebars urlTemplate: type: string description: Specifies the pattern for url generation. isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - rev - name - template ExistingLayoutMapping9: &ref_24 type: object description: An existing layout mapping. properties: id: type: string description: The ID of the layout mapping. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 example: e0192c4c-9633-4853-856a-ce04e37ec40c rev: type: string description: The current revision of the layout mapping. minLength: 1 example: 1d5fc65f4cd277eb5340355db7ecdfde75 name: type: string description: The name of the layout mapping. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 example: Sample layout mapping classification: type: string description: Indicates the type of this document. enum: - layout-mapping creatorId: type: string description: The ID of the user that created the layout mapping. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: > The display name of the user that created the layout mapping. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson created: type: string description: >- The created date of this layout mapping in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time example: '2016-11-02T06:28:47Z' lastModifierId: type: string description: The ID of the user that last modified the layout mapping. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f lastModifier: type: string description: > The display name of the last user that modified the layout mapping. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson lastModified: type: string description: >- The last modified date of this layout mapping in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time example: '2016-11-02T06:28:47Z' path: type: string description: >- Optional path to associate with the layout mapping. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myLayoutMappings/SampleMapping.json tags: type: array items: type: string uniqueItems: true example: - news - sample type: *ref_20 mappings: type: array description: The mapped layouts. items: *ref_21 minItems: 1 maxItems: 1 isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - rev - name - type - mappings ResolvedLayout9: &ref_23 type: object description: An existing layout returned from one of the resolution end points. properties: id: type: string description: The ID of the layout. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 example: f26044ca-d92d-49e8-acd9-00563c1e0db9 rev: type: string description: The current revision of the layout. minLength: 1 example: 139c63397272172e73f52d22f22f606f6c name: type: string description: The name of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 example: Sample layout description: type: string description: The description of the layout. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' example: An example description of the sample layout classification: type: string description: Indicates the type of this document. enum: - layout path: type: string description: >- Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myLayouts/SampleLayout.json prerender: type: boolean description: Indicates if the layout should be prerendered. default: false example: false creatorId: type: string description: The ID of the user that created the layout. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f creator: type: string description: > The display name of the user that created the layout. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson created: type: string description: >- The created date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time lastModifierId: type: string description: The ID of the user that last modified the layout. example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f lastModifier: type: string description: > The display name of the last user that modified the layout. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: Thomas Watson lastModified: type: string description: >- The last modified date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time tags: type: array items: type: string uniqueItems: true example: - news - sample template: type: string minLength: 1 example: /mytemplates/template.hbs templateType: type: string description: >- Specifies the type of template associated with this layout. This field is required when prerender field is set to true. enum: - handlebars - angular default: handlebars example: handlebars thumbnail: type: object description: >- The reference to the asset that should act as the thumbnail of this layout. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: > The path of the asset. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: /sales/images/hub.png url: type: string description: > The URL of the asset. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. example: /authoring/v1/resources/d45c83a8-2738-48a2-89e1-35256ee16283.jpg LayoutQueryResult9: &ref_191 type: object description: A query result that returns layouts. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_22 ResolvedLayoutQueryResult9: &ref_192 type: object description: A query result that returns resolved layouts. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_23 LayoutMappingQueryResult9: &ref_195 type: object description: A query result that returns layout mappings. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_24 TypeMapping9: *ref_20 LayoutMappingEntry9: *ref_21 LayoutReference9: *ref_19 ErrorResult9: &ref_190 type: object description: an error response. properties: errors: type: array items: &ref_25 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code. key: type: string description: The message key. message: type: string description: The error message. description: type: string description: Optional detailed error message. more_info: type: string description: Optional additional information for the message. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user. enum: - API - USER level: type: string description: Indicates the message level. enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. requestId: type: string description: The current request ID. service: type: string description: The name of the service that produced the error. requestMethod: type: string description: The Http method type of the current request. requestUri: type: string description: The current request uri. Message9: *ref_25 Library10: &ref_26 type: object description: A library representation. properties: id: type: string description: The ID of the library. example: 918e7c31-a662-487b-9a71-5b8665211d5a rev: type: string description: The revision of the library. readOnly: true example: 2-c839bbb8844549c2e298275c4b2adcb8 name: type: string description: The name of the library. example: Sample Library description: type: string description: The description of the library. example: An example description of the sample library. creatorId: type: string readOnly: true description: The ID of the user that created the library. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e created: type: string format: date-time readOnly: true description: The date and time the library was created. creator: type: string readOnly: true description: The name of the user who originally created the library. lastModifierId: type: string readOnly: true description: The ID of the user that last modified the library. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e lastModified: type: string format: date-time readOnly: true description: The date and time the library was last modified. lastModifier: type: string readOnly: true description: The name of the user who last modified the library. systemModified: type: string format: date-time readOnly: true description: The date and time the library was last modified by the system. isSystem: type: boolean description: >- Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic. default: false access: type: string description: The access level of the library. enum: - public - private - protected example: private owners: type: array description: >- A list of owners that are able to approve items inside libraries when managed approvals is on. items: type: object properties: id: type: string description: The ID of the user that has owner access. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e displayName: type: string readOnly: true description: The name of the user that has owner access. contributors: type: array description: >- A list of contributors that are able to contribute to the library when it is not public. items: type: object properties: id: type: string description: The ID of the user that has contributor access. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e displayName: type: string readOnly: true description: The name of the user that has contributor access. tags: type: array description: The tags describing the library. items: type: string uniqueItems: true example: - news - movies required: - id - name - rev NewLibrary10: &ref_198 type: object properties: name: type: string description: The name of the library. example: Sample Library description: type: string description: The description of the library. example: An example description of the sample library. access: type: string description: The access level of the library. enum: - public - private - protected example: private owners: type: array description: >- A list of owners that are able to approve items inside libraries when managed approvals is on. items: type: object properties: id: type: string description: The ID of the user that has owner access. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e contributors: type: array description: >- A list of contributors that are able to contribute to the library when it is not public. items: type: object properties: id: type: string description: The ID of the user that has contributor access. example: e98c185a-cafb-4c32-ad94-dd4ffaa28a7e tags: type: array description: The tags describing the library. items: type: string uniqueItems: true example: - news - movies isSystem: type: boolean description: >- Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic. default: false required: - name QueryResult10: &ref_197 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of libraries to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: /authoring/v1/libraries?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: /authoring/v1/libraries?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: /authoring/v1/libraries?offset=0&limit=50 items: type: array items: *ref_26 Count10: &ref_199 type: object properties: count: type: integer example: count: 348 required: - count ErrorResponse10: &ref_196 type: object description: An error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The HTTP method type of the current request requestUri: type: string description: The request URI errors: type: array items: &ref_27 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end-user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error10: *ref_27 IncomingReferenceMetadata11: &ref_31 type: object properties: id: type: string example: 9aefea92-2dd4-42c3-8999-10acbcfcc054 description: the id of the item. classification: &ref_28 type: string example: content description: >- Every item in content hub has a classification the classification and id combine to make a unique id across different types of items in content hub. metadata: &ref_29 type: object description: >- The metadata property is only added if you use include=metadata. Additionally the contents of this object mirrors what is returned by search which is why the search `fl` parameter is available for use here. So with fl=id,name The name and id will be added. The id will always be included example: - name: Article 1 - id: 'content:9aefea92-2dd4-42c3-8999-10acbcfcc054' BatchIncomingReferenceMetadata11: &ref_204 type: array items: type: object properties: id: type: string example: 9aefea92-2dd4-42c3-8999-10acbcfcc054 description: the id of the item. classification: *ref_28 metadata: type: object description: 'Basic metadata like name, and does not include search metadata.' example: - name: Article 1 Classification11: *ref_28 SearchMetadata11: *ref_29 OutgoingReferenceMetadata11: &ref_30 type: object properties: id: type: string classification: *ref_28 metadata: *ref_29 included: description: >- The included are outgoing references of this item we also fetched for metadata and references. Another way to put it is in the Graph traversal of the reference we walked these edges. Every id in here is guaranteed to also have a corresponding object in the references. example: - 'content:2a1e4698-2b95-4f61-be9f-1a1ca477b3c1' - 'asset:792c31ac-3a79-4183-8b7e-fce05e6dcc39' - 'content-type:5b839b21-0b6e-412c-8421-6bde66ca624c' type: array items: type: string excluded: description: >- If an outgoing reference is not included, then it is excluded. If its excluded we didn't attempt to fetch information about these items (and their references). This can happen for a couple of reasons. The common one is because the reference was filtered out. See the filter information to find out how filters work. Another reason is if the query terminated early. This can happen if the type: array items: type: string additionalProperties: false OutgoingReferencesResponse11: &ref_201 type: object properties: result: type: object properties: status: enum: - ok - partial depth: type: integer next: type: object properties: roots: type: array items: type: string depth: type: integer fl: type: array items: type: string metadata: type: boolean filters: type: object properties: classifications: type: array items: type: string statuses: type: array items: enum: - draft - ready - retired filterType: enum: - include - exclude additionalProperties: false root: type: string roots: type: array items: type: string references: type: object additionalProperties: *ref_30 OutgoingReferenceRequest11: &ref_200 type: object properties: filters: type: object properties: classifications: type: array items: type: string statuses: type: array items: enum: - draft - ready - retired filterType: enum: - include - exclude additionalProperties: false depth: type: integer fl: type: array items: type: string metadata: type: boolean root: type: string roots: type: array items: type: string additionalProperties: false IncomingReferencesResponse11: &ref_205 type: object properties: limit: type: integer description: The page size. example: 50 offset: type: integer description: The number of items to skip from the beginning of the list. example: 0 href: type: string description: A link to the current page. example: >- /authoring/v1/references/incoming/content/2a1e4698-2b95-4f61-be9f-1a1ca477b3c1?offset=50&limit=50 next: type: string description: A link to the next page. Only shown if a next page exists. example: >- /authoring/v1/references/incoming/content/2a1e4698-2b95-4f61-be9f-1a1ca477b3c1?offset=100&limit=50 previous: type: string description: A link to the previous page. Only shown if a previous page exists. example: >- /authoring/v1/references/incoming/content/2a1e4698-2b95-4f61-be9f-1a1ca477b3c1?offset=0&limit=50 items: type: array items: *ref_31 ErrorResponse11: &ref_202 type: object description: an error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The Http method type of the current request requestUri: type: string description: The request uri errors: type: array items: &ref_32 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error11: *ref_32 IncomingReferenceRequest11: &ref_203 type: object properties: limit: type: integer description: maximum number of references return for each item. excludeRoots: type: boolean description: excludes the references that are already in the requested roots. excludeSoftReferences: type: boolean description: whether to exclude soft incoming references. root: type: string roots: type: array items: type: string additionalProperties: false DeletedQueryResult11: type: object properties: limit: type: integer description: The page size. offset: type: integer description: The number of items to skip from the beginning of the list. href: type: string description: A link to the current page. next: type: string description: A link to the next page. Only shown if a next page exists. previous: type: string description: A link to the previous page. Only shown if a previous page exists. items: type: array items: &ref_33 type: object properties: id: type: string description: The id of the deleted item example: a3b00294-c59e-44db-a4f1-b625db0a42ab classification: type: string description: The classification of the deleted item example: content lastModified: type: string format: date-time description: The date and time the item was deleted. rev: type: string description: The revision of the item that was deleted. example: 2-c839bbb8844549c2e298275c4b2adcb8 deleted: type: boolean description: >- The property to indicate whether the item is deleted. For DeletedItem, this will always be true. example: true metadata: type: object description: >- Metadata of the deleted item which does not include search metadata. Additionally, the metadata property is only added if you use include=metadata. required: - id - classification - lastModified - rev - deleted required: - limit - offset - href - items DeletedItem11: *ref_33 RenditionParameters12: &ref_34 type: object properties: locationX: type: integer example: 50 description: >- Offset from the top left corner in the x dimension for where the crop will begin locationY: type: integer example: 100 description: >- Offset from the top left corner in the y dimension for where the crop will begin width: type: integer example: 200 description: Width of the crop height: type: integer example: 200 description: Height of the crop scale: type: number example: 1.5 description: Size image will be scaled to asset: type: object properties: id: type: string description: The id of the asset this rendition is for example: 27c621ed48921b7338b84b4f415cba6b required: - id id: type: string description: The id of the rendition to create example: 0a800487f06d71eaf4cffdfde1ab28bc required: - asset Rendition12: &ref_37 allOf: - *ref_34 - type: object properties: id: type: string description: The id of the rendition readOnly: true example: 0a800487f06d71eaf4cffdfde1ab28bc rev: type: string description: The revision of the rendition readOnly: true example: 2-c839bbb8844549c2e298275c4b2adcb8 classification: type: string readOnly: true enum: - rendition description: The classification of a rendition is always "rendition" fileName: type: string readOnly: true description: File name of the resource mediaType: type: string readOnly: true description: Media type of the resource resource: type: string description: the id of the uploaded resource this rendition is for example: 67c621ed48921b7338b84b4f415cba6b links: title: Links type: object readOnly: true properties: self: description: Relative link to the rendition example: href: /authoring/v1/renditions/0a800487f06d71eaf4cffdfde1ab28bc type: object properties: &ref_35 href: type: string description: Relative url readOnly: true example: /a/b/c/1234 required: &ref_36 - href media: description: Relative link to the rendition applied to the resource example: href: >- /authoring/v1/resources/67c621ed48921b7338b84b4f415cba6b?resize=1.5xw:1.5xh&crop=200:200;50:100 type: object properties: *ref_35 required: *ref_36 asset: description: Relative link to the asset example: href: /authoring/v1/assets/27c621ed48921b7338b84b4f415cba6b type: object properties: *ref_35 required: *ref_36 resource: description: Relative link to the rendition example: href: /authoring/v1/resources/67c621ed48921b7338b84b4f415cba6b type: object properties: *ref_35 required: *ref_36 required: - self - media - asset - resource required: - id - rev - classification - fileName - mediaType - resource Link12: type: object properties: *ref_35 required: *ref_36 QueryResult12: &ref_206 type: object properties: limit: type: integer description: The page size. offset: type: integer description: The number of items to skip from the beginning of the list. href: type: string description: A link to the current page. next: type: string description: A link to the next page. Only shown if a next page exists. previous: type: string description: A link to the previous page. Only shown if a previous page exists. items: type: array items: *ref_37 required: - limit - offset - href - items ErrorResponse12: *ref_1 Error12: *ref_38 Count13: &ref_212 type: object properties: count: type: integer NewImageProfile13: &ref_209 type: object description: An new image profile. properties: name: type: string description: The name of the image profile. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 description: type: string description: The description of the image profile. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' classification: enum: - image-profile created: type: string description: >- Optional creation date of this image profile in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. Value is ignored if set in the future. format: date-time tags: type: array items: type: string uniqueItems: true example: - news - sample dimensions: type: array items: &ref_39 type: object description: A indiviual dimension within an image profile. properties: label: type: string description: The dimension label. key: type: string description: The dimension key. description: type: string description: The description of the dimension. width: type: number description: The dimension's width height: type: number description: The dimension's height isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - name - classification - dimensions ExistingImageProfile13: &ref_40 type: object description: An existing image profile. properties: id: type: string description: The ID of the image profile. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 rev: type: string description: The current revision of the image profile. minLength: 1 name: type: string description: The name of the image profile. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 description: type: string description: The description of the image profile. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' classification: enum: - image-profile creatorId: type: string description: The ID of the user that created the image profile. minLength: 1 creator: type: string description: > The display name of the user that created the image profile. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. created: type: string description: >- The created date of this image profile in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 lastModifierId: type: string description: The ID of the user that last modified the image profile. minLength: 1 lastModifier: type: string description: > The display name of the last user that modified the image profile. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. lastModified: type: string description: >- The last modified date of this image profile in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 tags: type: array items: type: string uniqueItems: true example: - news - sample dimensions: type: array items: *ref_39 isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - rev - name - classification - creatorId - dimensions MultiImageProfile13: type: object properties: notFound: type: array description: >- A list of requested ids which were not retrieved because they did not exist. example: - 579c2232-7398-4c8b-921d-3932bfc45d19 - 448e8d63-ed15-4d59-85e5-53908a84ca93 items: type: string errors: type: array description: >- A list of requested ids whch were not retrieved due to system errors, see the `messages` attribute for a detailed error information. example: - 6c622bbb-5f5b-45d4-89e1-fce1c054138f - 9560c8de-b37c-4874-93fe-7e585339e9f9 items: type: string items: type: object additionalProperties: *ref_40 example: 162119d1-9757-4773-acd1-46126dbf69d9: id: 162119d1-9757-4773-acd1-46126dbf69d9 rev: string name: string description: string creatorId: string creator: string created: '2018-07-09T06:17:29.079Z' lastModifierId: string lastModifier: string lastModified: '2018-07-09T06:17:29.079Z' tags: - news - sample dimensions: - label: string key: string description: string width: 0 height: 0 messages: type: object description: Provides detailed information on any not found or system errors additionalProperties: &ref_41 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code. key: type: string description: The message key. message: type: string description: The error message. description: type: string description: Optional detailed error message. more_info: type: string description: Optional additional information for the message. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user. enum: - API - USER level: type: string description: Indicates the message level. enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. example: 579c2232-7398-4c8b-921d-3932bfc45d19: code: 2500 key: document.not.found.1 message: Item 579c2232-7398-4c8b-921d-3932bfc45d19 not found. category: USER level: ERROR parameters: id: 579c2232-7398-4c8b-921d-3932bfc45d19 locale: en-US 448e8d63-ed15-4d59-85e5-53908a84ca93: code: 2500 key: document.not.found.1 message: Item 448e8d63-ed15-4d59-85e5-53908a84ca93 not found. category: USER level: ERROR parameters: id: 448e8d63-ed15-4d59-85e5-53908a84ca93 locale: en-US 6c622bbb-5f5b-45d4-89e1-fce1c054138f: code: 2026 key: error.retrieve.document.2 message: >- Error retrieving image-profile document with ID 6c622bbb-5f5b-45d4-89e1-fce1c054138f. category: API level: ERROR parameters: classification: image-profile id: 6c622bbb-5f5b-45d4-89e1-fce1c054138f locale: en-US 9560c8de-b37c-4874-93fe-7e585339e9f9: code: 2026 key: error.retrieve.document.2 message: >- Error retrieving image-profile document with ID 9560c8de-b37c-4874-93fe-7e585339e9f9. category: API level: ERROR parameters: classification: image-profile id: 9560c8de-b37c-4874-93fe-7e585339e9f9 locale: en-US Dimension13: *ref_39 ImageProfileQueryResult13: &ref_211 type: object description: A query result that returns image profiles. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_40 ErrorResult13: &ref_210 type: object description: an error response. properties: errors: type: array items: *ref_41 requestId: type: string description: The current request ID. service: type: string description: The name of the service that produced the error. requestMethod: type: string description: The Http method type of the current request. requestUri: type: string description: The current request uri. Message13: *ref_41 ErrorResponse14: *ref_2 Error14: *ref_42 QueryResult14: &ref_215 type: object properties: limit: type: integer description: The page size. offset: type: integer description: The number of items to skip from the beginning of the list. href: type: string description: A link to the current page. next: type: string description: A link to the next page. Only shown if a next page exists. previous: type: string description: A link to the previous page. Only shown if a previous page exists. items: type: array items: &ref_43 type: object properties: id: type: string description: The id of the resource example: 2322e04f11e47edbc6505ad8294ebd70 created: type: string format: date-time description: The date and time the resource was created. required: - id - created required: - limit - offset - href - items ResourceMetadata14: *ref_43 NewReview15: &ref_216 type: object properties: name: type: string description: The name of the review. example: Sample Review targetDate: type: string format: date-time description: Optional. Set a target date for when the review is due and must end. example: '2018-01-22T03:00:20.945Z' approvers: type: array description: Approvers' user ID for the review. items: &ref_44 title: User type: object description: A user object with user ID. properties: id: type: string example: 45341daf-6b42-40c9-8aea-e9e24bf83b0a uniqueItems: true items: type: array description: >- Provide the ID of the items that you want to submit for review. The unique ID (uid) is the items classification and the ID combined to create an ID that is unique across all items in Content. items: &ref_45 title: Unique document ID type: object description: >- The unique document ID is the items classification and the ID combined to create an ID that is unique across all content hub items. properties: id: type: string example: a9e1e857-4eb3-4994-9214-3ed739a9987b classification: enum: - asset - content example: content description: The classification of the item. uniqueItems: true required: - name Review15: &ref_217 title: Review Schema type: object properties: id: type: string description: The ID of the review. example: 0d36aaf9-ddb3-4f3c-8582-5a0cea2c48b4 rev: type: string description: The current revision of the review. example: 1-b79b6fe8de3e2b63c45895f733482774 classification: type: string description: The review's classification. example: review readOnly: true name: type: string description: The name of the review. example: Sample Review targetDate: type: string format: date-time description: Optional. Set a target date for when the review is due and must end. example: '2018-01-22T03:00:20.945Z' status: type: string readOnly: true description: >- The status of a review. The initial status of a review is active, changed to complete when it is ended. enum: - active - complete approvalStatus: type: string readOnly: true description: >- The approval status of a review. The initial status of a review is not-approved, changed to approved when all items has been approved. enum: - approved - not-approved completed: type: string format: date-time description: >- The completed date of this review in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. example: '2018-01-22T03:00:20.945Z' approvers: type: array description: Approvers' user ID for the review. items: *ref_44 uniqueItems: true approvals: type: array description: Approvals for a review. readOnly: true items: &ref_46 title: Approval Schema type: object properties: user: *ref_44 date: type: string format: date-time readOnly: true description: >- The approved date in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. example: '2018-01-22T03:00:20.945Z' items: type: array description: The ID of the items that been approved in a approval. items: *ref_45 readOnly: true rejections: type: array description: Rejections for a review. readOnly: true items: &ref_47 title: Rejection Schema type: object properties: user: *ref_44 date: type: string format: date-time readOnly: true description: >- The approved date in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. example: '2018-01-22T03:00:20.945Z' items: type: array description: The ID of the items that been rejected in a rejection. items: *ref_45 readOnly: true items: &ref_48 title: Unique ID list type: array description: >- Provide the ID of the items that you want to submit for review. The unique ID (uid) is the items classification and the ID combined to create an ID that is unique across all content hub items. items: *ref_45 uniqueItems: true lastModified: type: string format: date-time readOnly: true description: >- The last modified date of this review in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. example: '2018-01-22T03:00:20.945Z' lastModifierId: type: string readOnly: true description: The ID of the user that last modified the review. example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9 created: type: string format: date-time readOnly: true description: >- The created date of this review in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. example: '2018-01-22T03:00:20.945Z' creatorId: type: string description: The ID of the creator of the review. readOnly: true example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f required: - id - rev - name Approval15: *ref_46 Rejection15: *ref_47 UpdateReview15: &ref_219 type: object properties: rev: type: string description: The current revision of the document. example: 1-b79b6fe8de3e2b63c45895f733482774 name: type: string description: The name of the review. example: Sample Review targetDate: type: string format: date-time description: Optional. Set a target date for when the review is due and must end. example: '2018-01-22T03:00:20.945Z' approvers: type: array description: Approvers' user ID for the review. items: *ref_44 uniqueItems: true required: - rev - name UniqueIDs15: *ref_48 User15: *ref_44 DocumentID15: *ref_45 BulkRequest15: &ref_220 type: object properties: ids: *ref_48 required: - ids RejectRequest15: type: object properties: ids: *ref_48 comments: type: string example: Please correct remarks before submitting the content to review again description: >- Comments explaining the reason for the rejection/remarks. If present cannot be empty ("") or blank (" "). A 400 Bad Request response will occur for invalid comments. required: - ids ErrorResponse15: &ref_218 type: object description: An error response. properties: requestId: type: string description: The current request ID example: ee74a16b-fe23-adee-314f-7ae54b7b07a3 service: type: string description: The name of the service that produced the error example: prod-authoring-review requestMethod: type: string description: The HTTP method type of the current request example: GET requestUri: type: string description: The request URI example: /authoring/v1/review errors: type: array items: &ref_49 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code example: 1022 key: type: string description: The message key example: error.generic.invalid.user.id.1022 message: type: string description: The error message example: The id requested does not exist. description: type: string description: Optional detailed error message example: >- Please check the ID you provided is correct before retrying the request. more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. example: en required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error15: *ref_49 Documents16: *ref_50 Document16: *ref_51 collection16: type: object properties: fields: type: array description: the fields of the schema items: type: object required: - name properties: name: type: string type: type: string enum: - boolean - date - double - float - int - long - point - string - text_general indexed: type: boolean stored: type: boolean required: type: boolean multi-valued: type: boolean doc-values: type: boolean copy-source: type: string default-field: type: string description: >- Specifies the default search field on which to perform queries. To override this default for a query, use the qf request parameter. default-field-list: type: array description: >- Specifies the stored or docValues fields that are included in the query response. To override this default for a query, use the fl request parameter. items: type: string version-field: type: string description: >- Specifies the version field to use document centric versioning support. ignore-old-updates: type: boolean description: >- Specifies whether to silently ignore updates with a document version that is not great enough instead of responding with an HTTP Version Conflict error. unique-key: type: string description: >- Specifies the required field that is used as the unique key of documents in a search collection. ErrorMessage16: &ref_221 type: object description: This JSON object describes an error condition. properties: requestId: type: string description: The unique identifier of the request that failed. service: type: string description: The name of the service that reports the error. errors: type: array items: &ref_52 type: object description: This JSON object describes a specific error of an error condition. properties: code: type: integer description: >- An error code that is specific to the service that reports the error. message: type: string description: A message that describes what went wrong. description: type: string description: >- A more detailed explanation of the error condition and recommended steps to resolve the issue. more_info: type: string description: >- A URL pointing to a source that provides more information on this error. level: type: string enum: - ERROR - WARNING description: The severity of this error. parameters: type: object description: >- Additional properties that represent dynamic parts used in the 'message'. cause: type: object description: >- The error message that was produced by a downstream service and represents the cause of this error. locale: type: string description: >- The locale information of the text provided as 'message' and as 'description' of this error. required: - code - message required: - requestId - errors Error16: *ref_52 SiteCreatedUpdatedResponse17: &ref_226 title: Site Metadata update response description: Site Metadata update response type: object properties: id: type: string description: The ID of the site. rev: type: string description: The current revision of the document. name: type: string description: The name of the site. classification: type: string description: this is always `site` routingMode: type: string description: >- The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'. With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents. SiteMetaData17: &ref_53 title: Site Metadata description: Site Metadata type: object properties: id: type: string description: The ID of the site. rev: type: string description: The current revision of the document. name: type: string description: The name of the site. classification: type: string description: This is always `site` lastModified: type: string description: >- The last modified date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only. lastModifierId: type: string description: >- This is the user id of the user that modified the site metadata. This field is read only created: type: string description: >- The creation date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only creatorId: type: string description: >- This is the user id of the user that created the site metadata. This field is read only. routingMode: type: string description: >- The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'. With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents. SiteList17: &ref_222 type: object title: List of available sites description: List of available sites properties: items: type: array items: *ref_53 SiteCreate17: &ref_224 title: Creating Site Metadata description: Create Site Metadata type: object properties: id: type: string description: >- The ID of the site. If creating a draft of the default site the id must start with default. linkedDocId: type: string description: >- The linkedDocId for draft sites. This is an optional field, if provided specify the ID of the ready site to create a draft of. name: type: string description: The name of the site. This is a required field. status: type: string description: The status of the site metadata (i.e. draft) routingMode: type: string description: >- The is routingMode the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'. With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents. SiteUpdate17: &ref_225 title: Updating Site Metadata description: Updating Site Metadata type: object properties: id: type: string description: The ID of the site. rev: type: string description: The current revision of the document. This is a required field. name: type: string description: The name of the site. This is a required field. routingMode: type: string description: >- The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'. With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents. AllPages17: type: object title: List of all pages description: List of all pages from all sites properties: items: type: array items: &ref_54 title: Hierarchical Page Metadata description: Page Metadata of page in hierarchy type: object properties: id: type: string description: The ID of the page item. rev: type: string description: The current revision of the document. name: type: string description: The name of the page item. contentId: type: string description: The ID of the page content item this item represents. contentTypeId: type: string description: The ID of the page content type. position: type: string description: >- Position relative to sibling pages giving the order of the pages. Position is an integer value starting at 0. description: type: string description: Page description. layoutId: type: string description: Page layout template ID. segment: type: string description: Friendly URL segment. title: type: string description: Page title. parentId: type: string description: Not present if root page otherwise id of parent page classification: type: string description: This is always `page` children: type: array items: type: object description: >- This is an array of the hierarchical child pages of this hierarchical page hideFromNavigation: type: boolean description: >- This controls the visibility of the page in the site navigation menu. If set to `true` this page is hidden. If set to `true` on a parent page, it will override the corresponding flags in all descendant pages. Therefore, hiding a page will hide all its descendants in the site navigation menu. PageHierarchy17: &ref_228 type: object title: Hierachy of pages in the site description: Hierachy of pages in the site properties: items: type: array items: *ref_54 PageList17: &ref_230 type: object title: Modified pages list description: A list of pages in the site modified between certain dates properties: items: type: array items: &ref_55 title: Page Metadata description: Page Metadata type: object properties: id: type: string description: The ID of the page item. rev: type: string description: The current revision of the document. name: type: string description: The name of the page item. contentId: type: string description: The ID of the page content item this item represents. contentTypeId: type: string description: The ID of the page content type. position: type: string description: >- Position relative to sibling pages giving the order of the pages. Position is an integer value starting at 0. description: type: string description: Page description. layoutId: type: string description: Page layout template ID. segment: type: string description: Friendly URL segment. title: type: string description: Page title. parentId: type: string description: Not present if root page otherwise id of parent page classification: type: string description: This is always `page` lastModified: type: string description: >- The last modified date of this page in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only. lastModifierId: type: string description: >- This is the user id of the user that modified the page. This field is read only created: type: string description: >- The creation date of this page in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only creatorId: type: string description: >- This is the user id of the user that created the page. This field is read only. hideFromNavigation: type: boolean description: >- This controls the visibility of the page in the site navigation menu. If set to `true` this page is hidden. If set to `true` on a parent page, it will override the corresponding flags in all descendant pages. Therefore, hiding a page will hide all its descendants in the site navigation menu. PageNew17: &ref_229 title: Create Page Metadata description: Creation of Page Metadata type: object properties: name: type: string description: The name of the page. contentId: type: string description: >- (Optional) The ID of the page content item to be associated with the new page. Specify this field when the new page is to be associated with an existing page content item. contentTypeId: type: string description: >- (Optional) The ID of the page content type to be used to create the new page content item for the new page. Specify this field when a page content item does not already exist. position: type: string description: >- (Optional) The position of the page relative to its sibling pages. Position is an integer value starting at 0. description: type: string description: Page description. layoutId: type: string description: >- (Optional) Page layout template ID for the new page content item. If not specified the default layout mapped to the content type will be used. segment: type: string description: Friendly URL segment. title: type: string description: Page title. parentId: type: string description: >- (Optional) The ID of the parent page. This should not be set if the new page is to be a root page. Otherwise, set this field to the ID of the parent page. hideFromNavigation: type: boolean description: >- (Optional) This controls the visibility of the page in the site navigation menu. Set it to `true` to hide the page. The default setting (if this field is not supplied) is `false`. If to `true` set on a parent page, it will override the corresponding flags in all descendant pages. Therefore, hiding a page will hide all its descendants in the site navigation menu. PageUpdate17: &ref_231 title: Update of Page Metadata description: Update of Page Metadata type: object properties: name: type: string description: The name of the page. id: type: string description: The ID of the page item. rev: type: string description: (Optional) The revision of the document. position: type: string description: >- The position of the page relative to its sibling pages. Position is an integer value starting at 0. description: type: string description: Page description. layoutId: type: string description: Page layout template ID. contentId: type: string description: The ID of the page content item this item represents. contentTypeId: type: string description: The ID of the page content type. segment: type: string description: Friendly URL segment. title: type: string description: Page title. parentId: type: string description: >- (Optional) The ID of the parent page. This should not be set if the new page is to be a root page. Otherwise, set this field to the ID of the parent page. classification: type: string description: this is always `page` hideFromNavigation: type: boolean description: >- (Optional) This controls the visibility of the page in the site navigation menu. Set it to `true` to hide the page. The default setting (if this field is not supplied) is `false`. If to `true` set on a parent page, it will override the corresponding flags in all descendant pages. Therefore, hiding a page will hide all its descendants in the site navigation menu. Page17: *ref_55 HierarchicalPage17: *ref_54 DeletePagesInBulkRequest17: title: Delete pages listed in the list of page ids description: Delete pages type: object properties: ids: type: array description: List of page Ids items: type: string DeletePagesInBulkResponse17: type: object properties: failedId: type: array description: List of failed Ids items: type: string MoveResult17: &ref_232 title: Target Parent After Move description: Target Parent Updated Values After Move type: object properties: id: type: string description: (optional) The ID of the parent page item. rev: type: string description: (optional) The latest revision of the parent page item document. DraftPageIds17: &ref_227 title: List of draft page ids in specified site to ready description: Publish the list of draft page Ids type: object properties: ids: type: array description: List of draft page Ids items: type: string ReadyPagesInBulkRequest17: title: Ready pages in bulk description: Publish the list of draft pages. type: object properties: ids: type: array description: List of draft pages items: &ref_56 title: Ready page List description: List of pages that needs to be moved to ready state type: object properties: id: type: string description: Page Id rev: type: string description: Latest page revision id classification: type: string description: Item classification context: &ref_57 title: Project details type: object properties: projectId: type: string description: Project Id publishDate: type: string description: The time that the project was published ReadyPagesIds17: *ref_56 ProjectContext17: *ref_57 ReadyPagesInBulkResponse17: type: object properties: failedId: type: array description: List of failed Ids items: type: string CreateDraftPagesInBulkRequest17: title: Create draft pages in bulk description: List of draft pages to create. type: object properties: ids: type: array description: List of draft pages items: &ref_58 title: Drafts to create page List description: List of pages to be created as drafts type: object properties: id: type: string description: Page Id rev: type: string description: Latest page revision id classification: type: string description: Item classification context: &ref_59 title: Project details type: object properties: projectId: type: string description: >- If specified, this is the id of the project that the drafts are to be created in preserveCreator: type: boolean description: Whether to preserve the creator property for each of the items isPublishingJob: type: boolean description: Whether the project is a publishing job or not. DraftPagesToCreateIds17: *ref_58 DraftsProjectContext17: *ref_59 CreateDraftPagesInBulkResponse17: type: object properties: successes: type: array description: List of successful Ids items: type: string no-ops: type: array description: List of Ids that had no operation performed on them items: type: string failedures: type: array description: List of failed Ids items: type: string Error17: &ref_60 title: Error description: Error type: object properties: code: type: integer message: type: string level: type: string description: type: string cause: type: object properties: code: type: integer message: type: string locale: type: string ErrorMessage17: &ref_223 title: ErrorMessage description: ErrorMessage type: object properties: service: type: string description: Service name. requestId: type: string description: Request ID. errors: type: array items: *ref_60 BlankContent18: &ref_240 type: object description: An blank content document. properties: classification: type: string description: the content document classification. enum: - content typeId: type: string description: the ID of the associated content-type. elements: type: object description: Represents the elements present on this content document. NewType18: &ref_233 type: object description: An new type document. properties: name: type: string description: The name of the type document. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 description: type: string description: The description of the type document. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' classification: &ref_61 type: string description: the type document classification. enum: - content-type kind: &ref_62 type: array description: | Identifies the sub-classification of the type document. Valid values include: * custom-ui: This type document has a custom user interface defined * embedded: This type document can be included within another type document * standalone: This type document can be used to create normal content items * page: This type document can be used to create site pages * landing-page: This type document can be used to create landing pages * email: This type document can be used to create email messages * site: This type document can be used to create sites items: type: string enum: - custom-ui - embedded - standalone - page - landing-page - email - site contentThumbnail: type: object description: The thumbnail settings for content using this type. properties: source: type: string enum: - imageElementOrType - imageElement - type - none imageElement: type: string description: >- When the 'source' is either 'imageElementOrType' or 'imageElement', specifies the element that will be used as the content thumbnail. required: - source created: type: string description: >- Optional creation date of this type document in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. Value is ignored if set in the future. format: date-time path: type: string description: >- Optional path to associate with this type document. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myTypes/SampleType.json tags: type: array items: type: string uniqueItems: true thumbnail: type: object description: > The reference to the asset that should act as the thumbnail of this type. The thumbnail can be referred to by either id or path. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: The path of the asset. example: /sales/images/hub.png url: type: string description: The url of the asset. example: /authoring/v1/resources/47d535ff288b3bd8383009abf82a9ea8 status: &ref_63 type: string description: the workflow status. enum: - draft - ready - retired uiExtensions: &ref_64 type: object description: >- Specifies any user interface extensions registered on this type document. properties: element: type: string description: > Registers a user interface extension that customizes the display of the content elements on the content form. The 'kind' of the type document should also include the value 'custom-ui'. icon: &ref_65 type: array description: > Specifies the type of icon to show for this type document within the Type user interface's element palette Only used when the type document has a kind that includes 'embedded' items: type: string enum: - category - datetime - formattedtext - file - group - image - link - location - number - reference - optionselection - text - toggle - variabletype - video elements: type: array description: Represents the elements present on this Type document. items: &ref_66 type: object description: > Represents an element within a content type. Only properties common to all elements are currently shown. For examples of each of the supported elements, see the documentation for the POST /types end point. properties: key: type: string description: >- The element identifer. Within content items, elements are referred to by key only. pattern: '^[A-Za-z_][A-Za-z0-9_]*$' maxLength: 50 label: type: string description: The display name of the element. pattern: ^(?!\\s*$).+ maxLength: 100 elementType: type: string description: Specifies the type of this element. enum: - category - datetime - file - group - image - link - location - number - reference - text - toggle - video allowMultipleValues: type: boolean description: > Indicates whether content items using this content-type can contain multiple values of this element. Valid for all element types except category, toggle and location. default: false minimumValues: type: integer description: >- When allowMulitpleValues is true, indicates the minimum number of values are that required. minimum: 0 maximum: 50 default: 0 maximumValues: type: integer description: >- When allowMulitpleValues is true, indicates the maximum number of values are that allowed. minimum: 0 maximum: 50 default: 50 fieldLabel: type: string description: > When allowMultipleValues is true, specifies a display name for each value within the multi valued list. pattern: ^(?!\\s*$).+ helpText: type: string description: >- The informational text to show the content author when setting the value of this element. required: type: boolean description: >- Indicates whether content items must specify a value for this element. default: false uiExtensions: type: object description: >- Specifies any user interface extensions registered for this element. properties: element: type: string description: > Registers a user interface extension that customizes the display of this element on the content form. Valid for all element types except group required: - key - label - elementType isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - name - description - classification - tags - status - elements ExistingType18: &ref_67 type: object description: An existing type document. properties: id: type: string description: The ID of the type document. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' minLength: 1 rev: type: string description: The current revision of the type document. minLength: 1 name: type: string description: The name of the type document. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 description: type: string description: The description of the type document. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' classification: *ref_61 kind: *ref_62 contentThumbnail: type: object description: The thumbnail settings for content using this type. properties: source: type: string enum: - imageElementOrType - imageElement - type - none imageElement: type: string description: >- When the 'source' is either 'imageElementOrType' or 'imageElement', specifies the element that will be used as the content thumbnail. required: - source creatorId: type: string minLength: 1 creator: type: string description: > The display name of the user that created this Type document. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. created: type: string description: >- The created date of this type document in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 lastModifierId: type: string minLength: 1 lastModifier: type: string description: > The display name of the last user that modified this Type document. This field is only returned when the 'include' query string option is set to 'ALL' or 'metadata'. This field is read only. lastModified: type: string description: >- The last modified date of this type document in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 path: type: string description: >- Optional path to associate with this type document. Must be unique. Will default to filesystem friendly version of /[NAME]. example: /myTypes/SampleType.json tags: type: array items: type: string uniqueItems: true thumbnail: type: object description: > The reference to the asset that should act as the thumbnail of this type. The thumbnail can be referred to by either id or path. properties: id: type: string description: The ID of the asset. example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f path: type: string description: The path of the asset. example: /sales/images/hub.png url: type: string description: The url of the asset. example: /authoring/v1/resources/47d535ff288b3bd8383009abf82a9ea8 status: *ref_63 linkedDocId: type: string description: >- Only present on Drafts created from existing Ready items, this property indicates the ID of the associated Ready item uiExtensions: *ref_64 icon: *ref_65 elements: type: array description: Represents the elements present on this Type document. items: *ref_66 links: &ref_69 type: object description: >- List of available operations, only shown when optional 'include' query string parameter includes 'links'. properties: self: type: object description: self link. properties: href: type: string schema: type: object description: > The Json-Schema representation of this Type document, which can be used to validate a content-item using this Type. This is the same document returned from the '/types/{id}/schema' end-point and is only returned when the 'include' query string option is set to 'ALL' or 'schema' mappings: type: object description: > The layout mappings of this Type document. This field is only returned when the 'include' query string option is set to 'ALL' or 'mappings'. isSystem: type: boolean description: Indicates whether this item is a 'system item' or not. default: false required: - rev - name - description - classification - creatorId - tags - status - elements ElementDef18: &ref_68 type: object description: An element definition. properties: id: type: string description: The ID of the element definition. pattern: '^[a-zA-Z0-9*.\-+_~$!'',()]*$' rev: type: string description: The current revision of the element definition. name: type: string description: The name of the element definition. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' minLength: 1 description: type: string description: The description of the element definition. pattern: '^[a-zA-Z0-9*. \-+_~$!'',()]*$' classification: &ref_70 type: string description: the element definition classification. enum: - element-definition creatorId: type: string minLength: 1 created: type: string description: >- The created date of this element definition in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 lastModifierId: type: string minLength: 1 lastModified: type: string description: >- The last modified date of this element definition in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only. format: date-time minLength: 1 tags: type: array items: type: string uniqueItems: true status: *ref_63 elementFragment: type: object description: The templated the current element. properties: key: type: string type: type: string TypeQueryResult18: &ref_236 type: object description: A query result that returns type documents. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_67 ElementDefQueryResult18: &ref_242 type: object description: A query result that returns element definitions. properties: offset: type: integer description: number of results to skip. limit: type: integer description: number of results to return. href: type: string description: the url of the current query. next: type: string description: >- the url for the next page of results. Only present if there are more results. previous: type: string description: >- the url for the previous page of results. Not present when on the first page. items: type: array items: *ref_68 TypeElement18: *ref_66 DocumentLinks18: *ref_69 WorkflowStatus18: *ref_63 TypeClassification18: *ref_61 TypeKind18: *ref_62 TypeIcon18: *ref_65 TypeUIExtensions18: *ref_64 ElementDefClassification18: *ref_70 Count18: &ref_238 type: object properties: count: type: integer ErrorResult18: &ref_234 type: object description: an error response. properties: errors: type: array items: &ref_71 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code. key: type: string description: The message key. message: type: string description: The error message. description: type: string description: Optional detailed error message. more_info: type: string description: Optional additional information for the message. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user. enum: - API - USER level: type: string description: Indicates the message level. enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. requestId: type: string description: The current request ID. service: type: string description: The name of the service that produced the error. requestMethod: type: string description: The Http method type of the current request. requestUri: type: string description: The current request uri. Message18: *ref_71 ValidationResult18: &ref_241 type: object description: a validation response. properties: successful: type: boolean description: Indicates if the validation was successful. info: type: array description: >- The array of informational messages, only present if the result has informational messages. items: *ref_71 warning: type: array description: >- The array of warning messages, only present if the result has warning messages. items: *ref_71 error: type: array description: >- The array of error messages, only present if the result has error messages. items: *ref_71 AllVersions20: &ref_243 type: object description: All versions for the specified item. properties: id: type: string description: The id of the item that these versions belong to example: 913b5e06ade9b2c215dc403e07368acc classification: type: string description: the classification of the item these versions belong to example: content deleted: type: boolean description: Whether the specified item is currently deleted. example: false versions: type: array description: The published versions associated to the specified item. items: &ref_73 type: object description: A specific version of an item. properties: containerType: enum: - deleted - current - item description: >- This indicates identifies the format of this container object in this API. "deleted" represents a deleted version so it won't have a link to the actual document. "item" represents the standard version and "current" is to collect draft versions number: type: string example: '2.0' description: The major version number link: type: string example: >- /authoring/v1/versions/content/2c51c263-cc86-4c76-8146-7b4a12c88cd1/2019-03-26T03:06:42.835Z description: >- A link to fetching the actual version, only available for containerType "item" timestamp: type: string format: date-time description: >- ISO-8601 timestamp of when the version was created. Also serves as the unique identifier for the version. Not available for containerType "current" example: '2019-11-02T06:28:47Z' user: type: string description: The display name of the user that created this version example: Thomas Watson userId: type: string description: The user identifier of the user that created this version example: a56305e1-201a-4961-a9d8-03fd026c0c19 drafts: type: array description: >- the draft versions that were made leading up to this published ersion. items: &ref_74 type: object description: a Draft version of the specified item properties: containerType: enum: - deleted - item description: >- This indicates identifies the format of this container object in this API. "deleted" represents a deleted version so it won't have a link to the actual document. "item" represents the standard version number: type: string example: '1.5' description: The minor version number link: type: string example: >- /authoring/v1/versions/content/2c51c263-cc86-4c76-8146-7b4a12c88cd1/2019-03-26T03:06:42.835Z description: >- A link to fetching the actual version, only available for containerType "item" timestamp: type: string format: date-time description: >- ISO-8601 timestamp of when the version was created. Also serves as the unique identifier for the version. example: '2019-11-02T06:28:47Z' user: type: string description: The display name of the user that created this version example: Thomas Watson userId: type: string description: The user identifier of the user that created this version example: a56305e1-201a-4961-a9d8-03fd026c0c19 event: &ref_72 type: string enum: - published - created - updated - retired - approved - restored - deleted - merged - moved-source - moved-target - review-started - review-ended description: | Version Event: * `published` - Published, The item was published and the `ready` item was updated * `created` - Created, The item was created * `updated` - Updated, the item was updated * `retired` - Retired, the item was retired * `approved` - Approved, the draft item was approved * `restored` - Restored, this item update is based off a previous version * `deleted` - Deleted, the item was deleted * `merged` - Merged, this draft was deleted and its changes was merged into the `ready` item * `moved-source` - Deleted by Move, This draft was deleted as it was moved into a project/publishing job * `moved-target` - Created by Move, this draft was created in this particular project/publishing job as a result of a move * `review-started` - Start Review, a review was started on this item * `review-ended` - Review Ended, a review was ended on this item example: updated event: *ref_72 required: - deleted - id - classification - versions Version20: *ref_73 DraftVersion20: *ref_74 VersionPolicyStatus20: &ref_245 type: object description: Response to indicate if the version policy status is in effect. properties: policy-status: type: string description: >- Flag that determines if the version policy is in effect; possible values - on, off, disabled. example: policyStatus: 'on' VersionPolicy20: type: object description: Representation of the version policy properties: policy-status: type: string description: >- Flag that determines if the version policy is in effect; possible values - on, off, disabled. retention-policies: type: object description: >- Retention policy with retention periods by document classification and workflow status. example: retentionPolicies: 'content:ready': - versionsToKeep: 10 daysToKeep: 365 kind: default - versionsToKeep: 0 daysToKeep: 0 kind: deletes VersionEvent20: *ref_72 ErrorResponse20: &ref_244 type: object description: An error response. properties: requestId: type: string description: The current request ID service: type: string description: The name of the service that produced the error requestMethod: type: string description: The Http method type of the current request requestUri: type: string description: The request uri errors: type: array items: &ref_75 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code key: type: string description: The message key message: type: string description: The error message description: type: string description: Optional detailed error message more_info: type: string description: Optional additional information for the message category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user enum: - API - USER level: type: string description: Indicates the message level enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. required: - code - key - message - description - more_info - category - level - parameters - field - locale required: - requestId - service - requestMethod - requestUri - errors Error20: *ref_75 Error21: title: Error description: Error type: object properties: &ref_76 code: type: integer message: type: string level: type: string description: type: string cause: type: object properties: code: type: integer message: type: string locale: type: string ErrorMessage21: &ref_246 title: ErrorMessage description: ErrorMessage type: object properties: service: type: string description: Service name. requestId: type: string description: Request ID. errors: type: object description: Error title: Error properties: *ref_76 BulkRetrievalRequest23: *ref_77 Content23: *ref_3 Error23: *ref_4 IdsListForBulkRetrieval23: *ref_78 FieldsListForBulkRetrieval23: *ref_79 ContentArray23: *ref_80 ConfigObject24: title: Config description: Configuration information for a tenant type: object properties: apiUrl: &ref_81 title: Url description: Properties of a URL type: object properties: auth: type: string description: >- The auth property is the username and password portion of the URL, also referred to as "userinfo". This string subset follows the protocol and double slashes (if present) and precedes the host component, delimited by an ASCII "at sign" (@). The format of the string is {username}[:{password}], with the [:{password}] portion being optional. hash: type: string description: >- The hash property consists of the "fragment" portion of the URL including the leading ASCII hash (#) character. host: type: string description: >- The host property is the entire lower-cased host portion of the URL, including the port if specified. hostname: type: string description: >- The hostname property is the lower-cased hostname portion of the host component without the port included. href: type: string description: >- The href property is the full URL string that was parsed with both the protocol and host components converted to lower-case. path: type: string description: >- The path property is a concatenation of the pathname and search components. pathname: type: string description: >- The pathname property consists of the entire path section of the URL. This is everything following the host (including the port) and before the start of the query or hash components, delimited by either the ASCII question mark (?) or hash (#) characters. No decoding of the path string is performed. port: type: string description: >- The port property is the numeric port portion of the host component. protocol: type: string description: >- The protocol property identifies the URL's lower-cased protocol scheme. query: type: string description: >- The query property is the query string without the leading ASCII question mark (?) search: type: string description: >- The search property consists of the entire "query string" portion of the URL, including the leading ASCII question mark (?) character. slashes: type: boolean description: >- The slashes property is a boolean with a value of true if two ASCII forward-slash characters (/) are required following the colon in the protocol. deliveryUrl: *ref_81 previewApiUrl: *ref_81 previewDeliveryUrl: *ref_81 authoringUIBaseUrl: *ref_81 Url24: *ref_81 SiteMetaData24: &ref_265 title: Site Metadata description: Site Metadata type: object properties: id: type: string description: The ID of the site. rev: type: string description: The current revision of the document. name: type: string description: The name of the site. classification: type: string description: The classification of site. This is always `site`. lastModified: type: string description: >- The last modified date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: This is the user ID of the user that modified the site metadata. created: type: string description: >- The creation date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: This is the user ID of the user that created the site metadata. pages: type: array items: &ref_82 title: Page Metadata description: Page Metadata type: object properties: id: type: string description: The ID of the page item. rev: type: string description: The current revision of the document. name: type: string description: The name of the page item. contentId: type: string description: The ID of the page content item this item represents. contentTypeId: type: string description: The ID of the page content type. position: type: string description: >- Position relative to sibling pages giving the order of the pages. Position is an integer value starting at 0. description: type: string description: Page description. layoutId: type: string description: Page layout template ID. segment: type: string description: Friendly URL segment. title: type: string description: Page title. parentId: type: string description: The ID of the parent page. Not present if it is the root page. classification: type: string description: The classification of the page. This is always `page`. lastModified: type: string description: >- The last modified date of this page in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: This is the user ID of the user that modified the page. created: type: string description: >- The creation date of this page in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: This is the user ID of the user that created the page. route: type: string description: This is the URL path of the page. url: type: string description: This is the server-relative URL. children: type: array items: type: object description: >- This is an array of the hierarchical child pages of this hierarchical page. description: The page hierarchy of the site. PageMetaData24: *ref_82 SearchEntry24: &ref_268 title: RenderingContextSearchEntry type: object properties: document: &ref_83 title: RenderingContext type: object properties: id: type: string description: The ID of the content item. rev: type: string description: The current revision of the document. name: type: string description: The name of the content item. classification: type: string description: >- The classification defines the document type. For content items, all documents are classified as "content". typeId: type: string description: The ID of the content type this item belongs to. locale: type: string description: 'The locale of the document (e.g "en", or "de").' lastModified: type: string format: date-time description: >- The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: The ID that last modified the content item. (read-only). created: type: string format: date-time description: >- The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: The ID of the creator layouts: description: The layouts of the content item type: object tags: type: array items: type: string uniqueItems: true description: The tags describing the content item. elements: type: object description: >- Defined by the type and captured in the schema given by the type, in a real content, this property will be filled with more information. description: type: string description: The description of the content item. type: type: string description: The link to the content type document this content is based on. RenderingContext24: *ref_83 ErrorMessage24: &ref_264 type: object description: This JSON object describes an error condition. properties: requestId: type: string description: The unique identifier of the request that failed. service: type: string description: The name of the service that reports the error. errors: type: array items: &ref_84 type: object description: This JSON object describes a specific error of an error condition. properties: code: type: integer description: >- An error code that is specific to the service that reports the error. message: type: string description: A message that describes what went wrong. description: type: string description: >- A more detailed explanation of the error condition and recommended steps to resolve the issue. more_info: type: string description: >- A URL pointing to a source that provides more information on this error. level: type: string enum: - ERROR - WARNING description: The severity of this error. parameters: type: object description: >- Additional properties that represent dynamic parts used in the 'message'. cause: type: object description: >- The error message that was produced by a downstream service and represents the cause of this error. locale: type: string description: >- The locale information of the text provided as 'message' and as 'description' of this error. required: - code - message required: - requestId - errors Error24: *ref_84 ErrorDefault25: *ref_85 Error25: *ref_5 Documents26: *ref_86 Document26: *ref_87 collection26: type: object properties: fields: type: array description: The fields of the schema items: type: object required: - name properties: name: type: string type: type: string enum: - boolean - date - double - float - int - long - point - string - text_general indexed: type: boolean stored: type: boolean required: type: boolean multi-valued: type: boolean doc-values: type: boolean copy-source: type: string default-field: type: string description: >- Specifies the default search field on which to perform queries. To override this default for a query, use the qf request parameter. default-field-list: type: array description: >- Specifies the stored or docValues fields that are included in the query response. To override this default for a query, use the fl request parameter. items: type: string version-field: type: string description: >- Specifies the version field to use document centric versioning support. ignore-old-updates: type: boolean description: >- Specifies whether to silently ignore updates with a document version that is not great enough instead of responding with an HTTP Version Conflict error. unique-key: type: string description: >- Specifies the required field that is used as the unique key of documents in a search collection. ErrorMessage26: &ref_275 type: object description: This JSON object describes an error condition. properties: requestId: type: string description: The unique identifier of the request that failed. service: type: string description: The name of the service that reports the error. errors: type: array items: &ref_88 type: object description: This JSON object describes a specific error of an error condition. properties: code: type: integer description: >- An error code that is specific to the service that reports the error. message: type: string description: A message that describes what went wrong. description: type: string description: >- A more detailed explanation of the error condition and recommended steps to resolve the issue. more_info: type: string description: >- A URL pointing to a source that provides more information on this error. level: type: string enum: - ERROR - WARNING description: The severity of this error. parameters: type: object description: >- Additional properties that represent dynamic parts used in the 'message'. cause: type: object description: >- The error message that was produced by a downstream service and represents the cause of this error. locale: type: string description: >- The locale information of the text provided as 'message' and as 'description' of this error. required: - code - message required: - requestId - errors Error26: *ref_88 Site27: &ref_276 title: Site type: object properties: id: type: string description: The ID of the site item. name: type: string description: The site item name. routingMode: type: string description: The routing mode can be "path" or "anchor" classification: type: string description: >- The classification defines the document type. For site items, all documents are classified as "site". lastModified: type: string description: >- The last modified date of this site item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: The ID of the user which applied the last modification of this item. created: type: string description: >- The created date of this site item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: The ID of the user that created this item. example: name: Example site routingMode: path classification: site lastModified: '2018-01-22T09:11:53.100Z' lastModifierId: 52fb9c98-822f-4d6b-99ed-a8b5e04f3782 creatorId: 00000000-0000-0000-0000-000000000009 created: '2018-01-10T12:01:57.188Z' id: 949c298a-03c9-21b5-9386-b8ea3c3e0ee3 Content27: &ref_278 title: Content type: object properties: id: type: string description: The ID of the content item. name: type: string description: The name of the content item. description: type: string description: The description text for this content item. classification: type: string description: >- The classification defines the document type. For site items, all documents are classified as "content". typeId: type: string description: The ID of the content type this item belongs to. locale: type: string description: 'The locale of the document (e.g "en", or "de").' lastModified: type: string format: date-time description: >- The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: The ID that last modified the content item. created: type: string format: date-time description: >- The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: The ID of the user that created this content item. kind: type: array items: type: string uniqueItems: true description: >- The kind of content. At least, one item kind element should be "site". tags: type: array items: type: string uniqueItems: true description: The tags which have been set for this content item. elements: type: object description: >- Defined by the type and capture in the schema given by the type, in a real content, this property will be filled with more information. type: type: string description: This is the ID of the content type document this content is based on. Page27: &ref_89 title: Page type: object properties: id: type: string description: The ID of the page item. name: type: string description: The page item name. segment: type: string description: The page segment name. title: type: string description: The page title. description: type: string description: The description text for this page item. route: type: string description: The route of this page item. hideFromNavigation: type: boolean description: Indicates whether the page is hidden in the navigation view or not. layoutId: type: string description: The name of the layout item for this page. contentId: type: string description: The ID of the content item which is associated with this page item. contentTypeId: type: string description: The ID of the content type of the page content. contentStatus: type: string description: >- The status of the content of this page. "ready" means that the content is in ready state. url: type: string description: A relative URL which locates this page item. position: type: number description: >- An ordinal value which determines the position of this page items in the order of page siblings. classification: type: string description: >- The classification defines the document type. For page items, all documents are classified as "page". lastModified: type: string description: >- The last modified date of this page item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. lastModifierId: type: string description: The ID of the user which applied the last modification of this item. created: type: string description: >- The created date of this page item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. creatorId: type: string description: The ID of the user that created this item. example: contentId: 980c6e51-1bf7-4fff-9386-b8e96aebf475 contentTypeId: 2f313485-dccd-4b3c-ab9b-d049841b1e45 description: '' hideFromNavigation: true layoutId: category-page-layout name: CategoryDefaultPage segment: categorydefaultpage title: '' classification: page lastModified: '2018-01-22T09:11:56.499Z' lastModifierId: 52fb9c98-822f-4d6b-99ed-a8b5e04f3782 contentStatus: ready created: '2018-01-11T15:07:46.153Z' creatorId: 52fb9c98-822f-4d6b-99ed-a8b5e04f3782 position: 10 route: /categorydefaultpage id: 288c1fc1-48b5-48b9-8254-f8d596a3a64e url: /664052ba-bdb9-49bf-8d33-dbe4a79b6520/categorydefaultpage Error27: &ref_277 type: object properties: service: type: string description: The name of the microservice that detected the error. requestId: type: string description: The ID of the request in which this error happened. errors: type: object description: This JSON object describes a specific error of an error condition. properties: code: type: integer description: >- An error code that is specific to the service that reports the error. message: type: string description: A brief error message. level: type: string enum: - WARNING - ERROR description: The error severity. description: type: string description: >- A detailed description that describes what caused the error, and how to proceed. cause: type: object description: The causing error. locale: type: string description: The locale setting of the message and description text. MultiPages27: &ref_279 title: MultiPages type: object properties: items: type: array description: An array of JSON objects that contain the requested page items. items: *ref_89 Tenant36: &ref_280 type: object required: - _id properties: name: type: string id: type: string description: read-only - UUID of the tenant _id: type: string description: DEPRECATED - read-only - UUID of the tenant. Use 'id' instead of _id locale: type: string description: The locale the UI is shown in readOnly: true defaultContentLocale: type: string description: The default locale for content contentLocales: type: array items: type: string description: Array of locales the content can be in default: - en-US locked: type: boolean description: >- Set to true if the tenant is 'locked' and should not have access to the system watsonConfidenceLevel: type: number format: double maxUploadSize: type: integer description: >- Max upload size - should apply to files/images/video unless useSingleUploadSize is false in which case the individual max uploads apply useSingleUploadSize: type: boolean description: >- Use the maxUploadSize to cover all uploads or use the individual max upload sizes maxUploadSizeFiles: type: integer description: Max upload size for files (if useSingleUploadSize is false) maxUploadSizeImage: type: integer description: Max upload size for images (if useSingleUploadSize is false) maxUploadSizeVideo: type: integer description: Max upload size for videos (if useSingleUploadSize is false) maxAuthors: type: integer maxContentItems: type: integer description: Max content items the tenant can have based on plan purchased maxStorageSize: type: integer description: 'Max amount of storage the tenant has, based on plan purchased' maxDataTransfer: type: integer description: >- Max amount of data transfer the tenant has per month, based on plan purchased isDAMEnabled: type: boolean readOnly: true tier: type: string description: The tier of the product the tenant has purchased ibmUniqueId: type: string isEdgeSideEnabled: type: boolean maxUserSessions: type: integer description: Max number of User sessions configDeliveryCacheMaxage: type: integer format: int64 description: >- Used when setting Cache-Control max-age response header - value in seconds - can not be negative value capability: type: string description: Indicates the capabilities supported by a tenant corsWhitelist: type: array items: type: string mandatoryAssetPublishApproval: &ref_91 type: object description: Can not be set for Base tiers properties: enabled: type: boolean description: True if mandatory approval is enabled exemptAssetTypes: type: array items: type: string mandatoryContentPublishApproval: &ref_92 type: object description: Cannot be set for Base tiers properties: enabled: type: boolean description: True if mandatory approval is enabled exemptContentTypes: type: array items: type: string deliveryAccess: &ref_93 type: object properties: secureAlways: type: boolean content: type: string assets: type: string ibmCommerce: &ref_90 type: object properties: tenantId: type: string apiGatewayHost: type: string previewSearchHost: type: string previewTransactionHost: type: string liveSearchHost: type: string liveTransactionHost: type: string environmentType: type: string ibmWca: type: object description: Properties for Campaign integration edgeToken: type: string description: String to hold edge configuration of the tenant importZip: type: object description: Information on most recent zip imported TenantAnonymous36: type: object properties: name: type: string readOnly: true id: type: string description: read-only - UUID of the tenant _id: type: string description: DEPRECATED - read-only - UUID of the tenant. Use 'id' instead of _id ibmCommerce: *ref_90 ibmWca: type: object description: Properties for Campaign integration readOnly: true TenantPut36: &ref_282 type: object properties: name: type: string id: type: string description: read-only - UUID of the tenant _id: type: string description: DEPRECATED - read-only - UUID of the tenant. Use 'id' instead of _id locale: type: string defaultContentLocale: type: string description: The default locale for content contentLocales: type: array items: type: string description: Array of locales the content can be in default: - en-US watsonConfidenceLevel: type: number format: double maxUploadSize: type: integer maxBulkUploadSize: type: integer useSingleUploadSize: type: boolean maxUploadSizeDocument: type: integer maxUploadSizeImage: type: integer maxUploadSizeAudio: type: integer maxUploadSizeVideo: type: integer maxAuthors: type: integer corsWhitelist: type: array items: type: string configDeliveryCacheMaxage: type: integer format: int64 description: >- Used when setting Cache-Control max-age response header - value in seconds - can not be negative value mandatoryAssetPublishApproval: *ref_91 mandatoryContentPublishApproval: *ref_92 ibmCommerce: *ref_90 ibmWca: type: object description: Properties for Campaign integration edgeToken: type: string description: String to hold edge configuration of the tenant importZip: type: object description: Information on most recent zip imported AssetPublishApproval36: *ref_91 ContentPublishApproval36: *ref_92 DeliveryAccess36: *ref_93 Error36: &ref_281 type: object properties: code: type: integer format: int32 message: type: string fields: type: string IbmCommerce36: *ref_90 TenantInfo38: &ref_94 type: object properties: baseUrl: type: string description: The baseUrl to call the services tenantId: type: string description: The tenantId of the available tenant description: Object containing the tenantId and baseUrl TenantArray38: &ref_284 type: array items: *ref_94 minItems: 0 maxItems: 100 description: The list of available tenants for the authenticated user Status38: &ref_283 type: object properties: service: type: string description: The service name requestId: type: string description: The current requestId httpStatus: type: integer description: The http return code Error41: &ref_95 description: >- This JSON record represents an individual error or warning contained in an error message. type: object properties: code: type: integer description: An error code defined by the User Profile service. message: type: string description: A message describing what went wrong. description: type: string description: >- Further explanation of the error condition and potential next steps to resolve the problem. more_info: type: string description: >- A URL pointing to a website that provides more information on the given error condition. level: type: string enum: - ERROR - WARNING description: The severity level of the message. parameters: type: object description: >- Additional properties reflecting the dynamic parts of the error condition. cause: type: object description: >- This property can be used to transport causing error message records produced by a down-stream service call. locale: type: string description: >- This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text. required: - code - message ErrorMessage41: &ref_287 description: This JSON record represents an error condition. type: object properties: errors: type: array items: *ref_95 requestId: type: string description: The ID of the failing request. service: type: string description: The name of the service serving the error message. required: - errors - requestId Id41: &ref_98 type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' description: The unique internal identifier of the user ExternalId41: &ref_99 type: string pattern: >- ^[0-9A-Z]{10}$|^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$, description: >- The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address. maxLength: 512 FirstName41: &ref_100 type: string description: The first name of the user maxLength: 512 uid41: &ref_102 type: string description: >- Acoustic ID of the user, if not present during POST call an Acoustic Id will be created for the user maxLength: 30 LastName41: &ref_101 type: string description: The last name of the user maxLength: 512 DisplayName41: &ref_103 type: string description: The name of the user that can be displayed in the UI maxLength: 512 Email41: &ref_104 type: string description: The email of the user that can be displayed in the UI format: email maxLength: 512 Roles41: &ref_113 type: array items: type: string enum: - authenticatedVisitor - viewer - editor - manager - admin minItems: 1 maxItems: 1 uniqueItems: true description: The roles of the user that will be used for access control RolesRetrieval41: &ref_105 type: array items: type: string enum: - authenticatedVisitor - viewer - editor - manager - admin minItems: 0 description: >- The roles of the user that will be used for access control (empty for the anonymous user) LastLogin41: &ref_107 type: string format: date-time description: Date when this user logged in for the last time before current session Created41: &ref_108 type: string format: date-time description: Date when this item was created LastModified41: &ref_110 type: string format: date-time description: Date when this item was modified for the last time HttpVerb41: &ref_97 type: string description: The supported HTTP methods enum: - GET - POST - PUT - DELETE Creator41: &ref_109 description: URI pointing to the user who has created the item type: object required: - id properties: id: type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' LastModifier41: &ref_111 description: URI pointing to the user who has modified the item type: object required: - id properties: id: type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' PrivacyNotices41: description: The privacy notices that the user has accepted type: object required: - history properties: history: type: array items: &ref_96 description: The privacy notice that the user has accepted type: object required: - version - locale properties: version: type: string minLength: 1 maxLength: 20 description: The version of the privacy notice. accepted: type: string format: date-time description: >- The date when the user accepted this version of the privacy notice. locale: type: string minLength: 1 maxLength: 20 description: The language in which the accepted privacy notice is written. additionalProperties: false description: >- The history of all accepted privacy notice versions, ordered chronologically. acceptRequired: type: boolean description: Defines if an acceptance of the latest privacy notice is required. _id PrivacyNoticeHistory41: *ref_96 PrivacyNotice41: description: The privacy notice that the user has accepted type: object required: - version - locale properties: version: type: string minLength: 1 maxLength: 20 description: The version of the privacy notice. accepted: type: string format: date-time description: The date when the user accepted this version of the privacy notice. locale: type: string minLength: 1 maxLength: 20 description: The language in which the accepted privacy notice is written. acceptRequired: type: boolean description: Defines if an acceptance of the latest privacy notice is required. additionalProperties: false PrivacyNoticeResponse41: &ref_112 description: The privacy notice that the user has accepted type: object required: - acceptRequired properties: version: type: string minLength: 1 maxLength: 20 description: The version of the privacy notice. accepted: type: string format: date-time description: The date when the user accepted this version of the privacy notice. locale: type: string minLength: 1 maxLength: 20 description: The language in which the accepted privacy notice is written. acceptRequired: type: boolean description: Defines if an acceptance of the latest privacy notice is required. additionalProperties: false UriSelf41: &ref_106 description: URI pointing to this document type: object required: - href - methods properties: href: type: string methods: type: array items: *ref_97 name: description: >- Single value object where key is the locale and value is the display name type: object User41: &ref_286 description: The user object that might be returned. type: object required: - externalId - id - roles properties: id: *ref_98 externalId: *ref_99 firstName: *ref_100 lastName: *ref_101 uid: *ref_102 displayName: *ref_103 email: *ref_104 roles: *ref_105 links: type: object required: - self properties: self: *ref_106 lastLogin: *ref_107 created: *ref_108 creator: *ref_109 lastModified: *ref_110 lastModifier: *ref_111 privacyNotice: *ref_112 additionalProperties: false EnrichedUser41: &ref_296 description: The user object that might be returned. type: object required: - externalId - id - roles properties: id: *ref_98 externalId: *ref_99 firstName: *ref_100 lastName: *ref_101 displayName: *ref_103 email: *ref_104 roles: *ref_105 links: type: object required: - self properties: self: *ref_106 lastLogin: *ref_107 created: *ref_108 creator: *ref_109 lastModified: *ref_110 lastModifier: *ref_111 privacyNotice: *ref_112 additionalProperties: true Approver41: description: The approver object that might be returned. type: object required: - id properties: id: *ref_98 firstName: *ref_100 lastName: *ref_101 displayName: *ref_103 additionalProperties: false EditorManagerAdmin41: description: The match object that might be returned. type: object required: - id properties: id: *ref_98 firstName: *ref_100 lastName: *ref_101 displayName: *ref_103 roles: *ref_113 additionalProperties: false UserCreation41: &ref_294 description: The user object that might be sent for user creation. type: object required: - externalId - roles properties: externalId: *ref_99 firstName: *ref_100 lastName: *ref_101 uid: *ref_102 displayName: *ref_103 email: *ref_104 roles: *ref_113 additionalProperties: false UserUpdate41: &ref_297 description: >- The user object that might be sent to replace the user. The fields `id`, `externalId`, `links`, `created`, `creator`, `lastModified`, and `lastModifier` will be ignored. type: object required: - id properties: id: *ref_98 externalId: *ref_99 firstName: *ref_100 lastName: *ref_101 uid: *ref_102 displayName: *ref_103 email: *ref_104 roles: *ref_113 links: type: object created: *ref_108 creator: *ref_109 lastModified: *ref_110 lastModifier: *ref_111 additionalProperties: false UserUpdateLogin41: description: >- The user object that might be sent to replace the user. The fields `id`, `externalId`, `links`, `created`, `creator`, `lastModified`, and `lastModifier` will be ignored. type: object required: - id properties: id: *ref_98 externalId: *ref_99 uid: *ref_102 firstName: *ref_100 lastName: *ref_101 displayName: *ref_103 email: *ref_104 roles: *ref_113 privacyNotice: *ref_112 links: type: object created: *ref_108 creator: *ref_109 lastModified: *ref_110 lastModifier: *ref_111 additionalProperties: false UriFirst41: &ref_114 description: URI pointing to the first sublist of items of the complete list type: object required: - href properties: href: type: string UriPrev41: &ref_115 description: URI pointing to the previous sublist of items of the complete list type: object required: - href properties: href: type: string UriNext41: &ref_116 description: URI pointing to the next sublist of items of the complete list type: object required: - href properties: href: type: string ItemList41: &ref_293 type: object required: - offset - limit properties: links: type: object required: - self - first properties: self: *ref_106 first: *ref_114 prev: *ref_115 next: *ref_116 offset: type: integer description: >- Number of skipped items, the first item in this sublist list will be (offset) limit: type: integer description: Maximum number of items in the current sublist ApproverList41: type: object required: - limit properties: links: type: object required: - self - first properties: self: *ref_106 first: *ref_114 prev: *ref_115 next: *ref_116 startkey: type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' description: The first item in this sublist list endkey: type: string pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' description: The first item in this sublist list limit: type: integer description: Maximum number of items in the current sublist WebhookProfile45: &ref_298 type: object description: A webhook profile. properties: id: type: string description: The ID of the webhook profile readOnly: true rev: type: string description: The current revision of the webhook profile. minLength: 1 readOnly: true classification: enum: - webhook-profile creatorId: type: string description: The ID of the user that created the webhook profile. minLength: 1 readOnly: true created: type: string description: >- The created date of this webhook profile in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. format: date-time minLength: 1 readOnly: true lastModifierId: type: string description: The ID of the user that last modified the webhook profile. minLength: 1 readOnly: true lastModified: type: string description: >- The last modified date of this webhook profile in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. format: date-time minLength: 1 readOnly: true webhooks: type: array description: The list of registered webhooks items: &ref_117 type: object description: An individual webhook. properties: url: type: string description: >- The URL to execute when firing the webhook. Must be an absolute URL. example: 'http://www.my-webhook.com/myHooks' secret: type: string description: > Optional secret token to use when creating the hash signature to send in a http header. When a secret is specified, the webhook will be sent with an additional `X-IBM-WCH-SIGNATURE` header whose value is the `HmacSHA1` hash of the request body (using the secret as the seed). Webhook receivers can generate their own `HmacSHA1` hash of the request body and compare it to the one sent to verify that the request came from Content. Once the webhook has been saved, a `secretId` will be returned instead of the actual secret. secretId: type: string description: > The ID which was generated to represent your secret. When updating a webhook, include the `secretId` to continue using the same secret. You may also provide a new `secret` to change it or exclude the `secretId` to remove the secret. active: type: boolean description: Optional flag to indicate whether the webhook is active. filter: type: object description: > Optional filter rules to limit when the webhook will fire. When multiple rules are specified, then ALL must match for the webhook to fire properties: eventType: type: array description: >- Optional event-types to limit the webhook to. When multiple event-types are specified, then the webhook will fire whenever ANY of the specified event-types occur. items: type: string enum: - create - update - delete example: - create - update classification: type: array description: >- Optional document classifications to limit the webhook to. When multiple classifications are specified, then the webhook will fire whenever changes occur to ANY of the specified classifications. items: type: string enum: - asset - category - comment - content - content-type - default-content - image-profile - layout - layout-mapping - project - review - taxonomy example: - asset - category - content status: type: array description: >- Optional document statuses to limit the webhook to. When multiple statuses are specified, then the webhook will fire whenever changes occur to documents in ANY of the specified statuses. items: type: string enum: - draft - ready - retired example: - draft - ready tags: type: array description: > Optional document tags to limit the webhook to. When multiple tags are specified, then the webhook will fire whenever changes occur to documents with ANY of the specified tags. Note: If tags are specified, then documents without tags will automatically fail the filter items: type: string uniqueItems: true example: - tag1 - processMe required: - url WebhookDef45: *ref_117 ErrorResult45: &ref_299 type: object description: an error response. properties: errors: type: array items: &ref_118 type: object description: 'an individual error, info or warning message.' properties: code: type: integer description: The message code. key: type: string description: The message key. message: type: string description: The error message. description: type: string description: Optional detailed error message. more_info: type: string description: Optional additional information for the message. category: type: string description: >- The message category whereby only user messages are designed to be shown to an end user. enum: - API - USER level: type: string description: Indicates the message level. enum: - INFO - WARNING - ERROR parameters: type: object description: The message parameters of this message. field: type: string description: >- Only present on field validation errors, indicates the field in error. locale: type: string description: The current locale used to produce the error message. requestId: type: string description: The current request ID. service: type: string description: The name of the service that produced the error. requestMethod: type: string description: The Http method type of the current request. requestUri: type: string description: The current request uri. Message45: *ref_118 error47: *ref_119 error_message47: *ref_120 localizedItem47: &ref_135 type: object required: - name properties: description: &ref_122 type: object description: An object holding the localized description for multiple languages name: &ref_121 type: object description: An object holding the localized title for multiple languages localizedItemCreation47: &ref_137 type: object required: - name properties: name: *ref_121 description: *ref_122 managedItem47: &ref_134 type: object required: - id - rev - created - creator - lastModified - lastModifier properties: links: type: object required: - self properties: self: &ref_127 type: object required: - href - methods description: URL pointing to this document properties: href: type: string maxLength: 1024 methods: type: array items: &ref_154 type: string enum: - GET - POST - PUT - DELETE name: description: >- Single value object where key is the locale and value is the display name type: object id: type: string description: Unique identifier representing a specific item maxLength: 64 rev: &ref_128 type: string maxLength: 64 description: A string identifying a specific version of the document created: &ref_129 type: string format: date-time description: Date when this item was created creator: &ref_130 type: object required: &ref_123 - id description: A reference to the user who has created the item properties: &ref_124 id: type: string maxLength: 64 lastModified: &ref_131 type: string format: date-time description: Date when this item was modified for the last time lastModifier: &ref_132 type: object required: &ref_125 - id description: A reference to the user who has modified the item properties: &ref_126 id: type: string maxLength: 64 managedItemCreation47: &ref_138 type: object properties: id: type: string description: Unique identifier representing a specific item maxLength: 64 rev: description: >- Will be ignored - just part of the API to allow for a full item being re-used for creation type: string maxLength: 64 created: description: >- Will be ignored - just part of the API to allow for a full item being re-used for creation type: string format: date-time creator: description: >- Will be ignored - just part of the API to allow for a full item being re-used for creation type: object required: *ref_123 properties: *ref_124 lastModified: description: >- Will be ignored - just part of the API to allow for a full item being re-used for creation type: string format: date-time lastModifier: description: >- Will be ignored - just part of the API to allow for a full item being re-used for creation type: object required: *ref_125 properties: *ref_126 managedItemUpdate47: &ref_139 type: object required: - rev - id properties: links: type: object properties: self: *ref_127 id: type: string description: Unique identifier representing a specific item maxLength: 64 rev: *ref_128 created: *ref_129 creator: *ref_130 lastModified: *ref_131 lastModifier: *ref_132 itemList47: &ref_140 type: object required: - offset - limit - count properties: links: type: object required: - self - first - last properties: self: *ref_127 first: &ref_156 type: object required: - href description: URI pointing to the first sublist of items of the complete list properties: href: type: string maxLength: 1024 prev: &ref_157 type: object required: - href description: URI pointing to the previous sublist of items of the complete list properties: href: type: string maxLength: 1024 next: &ref_158 type: object required: - href description: URI pointing to the next sublist of items of the complete list properties: href: type: string maxLength: 1024 last: &ref_159 type: object required: - href description: URI pointing to the last sublist of the complete list properties: href: type: string maxLength: 1024 offset: type: integer description: >- Number of skipped items, the first item in this sublist will be (1+offset) limit: type: integer description: Maximum number of items in the current sublist count: type: integer description: Number of items in the complete list unmanagedJobDefinition47: type: object properties: profile: &ref_150 type: object properties: contentFormat: &ref_155 type: string enum: - FULL - SIMPLE autoActivate: description: >- If true, a new site revision will become active directly after being created by a job which is based on this profile type: boolean enableRendering: description: >- Specifies if content rendering shall be performed while publishing content. type: boolean enableContentPublishing: description: Specifies if content shall be published type: boolean enableAssetPublishing: description: Specifies if assets shall be published. type: boolean assetUrlGenerationMode: type: string description: >- Asset URLs can be generated based on the asset path resulting in URLs easy to read, or based on the asset ID. URLs based on the asset ID can be cached more efficiently. enum: - PATH - ID cachePolicyAssetId: type: string maxLength: 64 description: >- This property represents the reference to the HTTP caching policy that shall be published to the delivery site. The reference is represented by an asset ID value. plugins: type: array items: type: string maxLength: 64 source: &ref_152 type: object properties: docs: &ref_147 type: object description: >- Map which enumerates the events that shall be published grouped by their classification ('content', 'asset', etc.). properties: content: &ref_133 type: object description: >- Map which enumerates the items that shall be published, grouped by their event type ('created', 'updated', etc.) properties: created: description: List of items that have been created type: array items: type: string updated: description: List of items that have been updated type: array items: type: string deleted: description: List of items that have been deleted type: array items: type: string page: *ref_133 site: *ref_133 asset: *ref_133 category: *ref_133 resource: *ref_133 jobDefinitionCore47: &ref_136 type: object properties: profile: &ref_160 type: object required: - id description: A reference to a publishing profile properties: id: type: string maxLength: 64 source: &ref_161 type: object required: - id description: A reference to a publishing source properties: id: type: string maxLength: 64 jobDefinition47: &ref_141 type: object allOf: - *ref_134 - *ref_135 - *ref_136 jobDefinitionCreation47: type: object description: Schema for creating a job definition. allOf: - *ref_137 - *ref_138 - *ref_136 jobDefinitionUpdate47: type: object description: Schema for updating a job definition. allOf: - *ref_137 - *ref_139 - *ref_136 jobDefinitions47: type: object description: >- Returns a (sub-)list of items from the complete list of jobDefinitions. At most [limit] items are returned. allOf: - *ref_140 required: - items properties: items: type: array items: *ref_141 job47: &ref_143 type: object allOf: - *ref_134 required: - state - mode properties: mode: &ref_142 type: string enum: - UPDATE - REBUILD description: >- Specifies if the site revision will be updated or rebuilt from scratch. Default is 'UPDATE' state: &ref_146 type: string description: Enumeration of publishing job states enum: - READY - BUILDING - PENDING childJobIds: description: >- If this job has been created manually, the childJob array contains the IDs of those jobs that have been triggered by this job. type: array items: type: string maxLength: 64 jobCreation47: &ref_300 type: object description: >- created job. When creating a job, you can specify the mode that can be used. properties: mode: *ref_142 jobs47: type: object description: >- Returns a (sub-)list of items from the complete list of jobs. At most [limit] items are returned. allOf: - *ref_140 required: - items properties: items: type: array items: *ref_143 siteRevisionCore47: &ref_144 type: object properties: state: type: string description: State of the site revision enum: - READY - BUILDING - PENDING autoPublishEnabled: description: >- If true, any updates affecting this site revision will be published automatically. Default is true. type: boolean lastSucceeded: type: string format: date-time description: >- Date when this site revision was last updated successfully (last time a job for that site revision completed successfully) active: type: boolean description: Indicates if this site revision is the active one. job: type: object required: - id description: Reference to the job that modified this site revision most recently properties: id: type: string maxLength: 64 siteRevision47: &ref_145 type: object allOf: - *ref_134 - *ref_135 - *ref_144 required: - state siteRevisionUpdate47: &ref_304 description: >- Only properties autoPublishEnabled, name and description will be updated, others will be ignored type: object allOf: - *ref_137 - *ref_139 - *ref_144 siteRevisions47: type: object description: >- Returns a (sub-)list of items from the complete list of site revisions. At most [limit] items are returned. allOf: - *ref_140 required: - items properties: items: type: array items: *ref_145 status47: &ref_302 type: object required: - id - created - messages - lastModified - state - tasks properties: id: type: string description: Unique identifier of associated job maxLength: 64 created: *ref_129 lastModified: *ref_131 state: *ref_146 tasks: type: array items: &ref_149 type: object properties: type: type: string description: Indicates which type of task is reported. enum: - PUBLISH_ASSET - PUBLISH_CATEGORY - PUBLISH_CONTENT - PUBLISH_PAGE - PUBLISH_SITE - PUBLISH_RESOURCE messageType: type: string description: Indicates if the task has been successful. enum: - ERROR - INFO - WARNING num: type: integer format: int32 total: type: integer format: int32 docs: *ref_147 messages: type: array items: &ref_148 type: object properties: id: type: string description: Unique identifier of the message maxLength: 64 text: type: string description: The message text maxLength: 512 locale: type: string description: Locale information for this message maxLength: 10 type: type: string description: 'The type of message. One of `ERROR`, `INFO`, or `WARNING`.' enum: - ERROR - INFO - WARNING message47: *ref_148 task47: *ref_149 profileCore47: *ref_150 profile47: &ref_151 type: object allOf: - *ref_134 - *ref_135 - *ref_150 profileCreation47: description: 'TBD: ' type: object allOf: - *ref_137 - *ref_138 - *ref_150 profileUpdate47: description: 'TBD: ' type: object allOf: - *ref_137 - *ref_139 - *ref_150 profileCreationForJobCreation47: description: 'TBD: ' type: object allOf: - *ref_138 - *ref_150 profiles47: type: object description: >- Returns a (sub-)list of items from the complete list of profiles. At most [limit] items are returned. allOf: - *ref_140 required: - items properties: items: type: array items: *ref_151 sourceCore47: *ref_152 source47: &ref_153 type: object allOf: - *ref_134 - *ref_135 - *ref_152 sourceCreation47: type: object allOf: - *ref_137 - *ref_138 - *ref_152 sourceUpdate47: type: object allOf: - *ref_137 - *ref_139 - *ref_152 sourceDocs47: *ref_147 docEvents47: *ref_133 sources47: type: object description: >- Returns a (sub-)list of items from the complete list of sources. At most [limit] items are returned. allOf: - *ref_140 required: - items properties: items: type: array items: *ref_153 jobState47: *ref_146 httpVerb47: *ref_154 contentFormat47: *ref_155 created47: *ref_129 lastModified47: *ref_131 rev47: *ref_128 description47: *ref_122 title47: *ref_121 jobMode47: *ref_142 site47: type: object description: An object holding the site information. properties: href: type: string maxLength: 1024 urlSelf47: *ref_127 urlFirst47: *ref_156 urlPrev47: *ref_157 urlNext47: *ref_158 urlLast47: *ref_159 urlCreator47: *ref_130 urlLastModifier47: *ref_132 profileRef47: *ref_160 siteRevisionRef47: type: object required: - id description: A reference to a site revision properties: id: type: string maxLength: 64 sourceRef47: *ref_161 ErrorResponse: description: This JSON record represents an error condition. type: object properties: errors: type: array items: description: >- This JSON record represents an individual error or warning contained in an error message. type: object properties: code: type: integer description: An error code message: type: string description: A message describing what went wrong. description: type: string description: >- Further explanation of the error condition and potential next steps to resolve the problem. more_info: type: string description: >- A URL pointing to a web site that provides more information on the given error condition. level: type: string enum: - ERROR - WARNING description: The severity level of the message. Default is error. parameters: type: object description: >- Additional properties reflecting the dynamic parts of the error condition. cause: type: object description: >- This property can be used to transport causing error message records produced by a down stream service calls. locale: type: string description: >- This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text. required: - code - message requestId: type: string description: The ID of the failing request. service: type: string description: The name of the service serving the error message. required: - errors - requestId paths: /authoring/v1/assets: get: tags: - Authoring assets summary: Retrieve all assets. description: >- Use this endpoint to retrieve all assets from the database.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: limit in: query description: >- Set the limit for the maximum number of assets to return in a single result. Set to 50 by default. required: false type: integer default: 50 - name: offset in: query description: >- Use the offset parameter to specify the number of assets to skip from the beginning of the list and return the rest. required: false type: integer default: 0 - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv responses: '200': description: >- Successfully lists a paged result view of all the asset in the database. schema: *ref_162 '429': &ref_165 description: >- Too Many Requests, the server has reached a limit, the request must be sent again at a later time. schema: $ref: '#/definitions/ErrorResponse' '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer post: tags: - Authoring assets summary: Create an asset. description: >- 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 consumes: - application/json - multipart/form-data produces: - application/json parameters: - name: asset in: body description: >- Provide all the data that is needed to create a new asset. This is only required when creating an asset and resource separately. The resource id is required. 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. required: true schema: type: object title: Asset Parameters properties: resource: type: string description: The id of the resource this asset is for name: type: string description: Name of the asset path: type: string description: >- The path to this asset, must begin with a leading slash. A unique constraint is placed on this path so that no other asset can have the same path. Paths begining with "/dxdam/" are managed assets. description: type: string description: Description of the asset tags: description: >- The "values" array defines the user selected tags. The other two properties "declined" and "suggested" relate directly to the interaction with the cognitive analysis feature. type: object properties: values: type: array items: type: string description: The name of the tag id: description: The id of the asset to create type: string categoryIds: description: >- The IDs of the categories that define how this asset is categorized. type: array items: type: string status: type: string description: >- The workflow status of the asset. This value can only be set for managed assets. enum: - ready - draft - retired example: resource: 8d21025d21e7b3595cbf630fb9d7212b path: /Screen Shot 2016-05-11 at 6.52.22 PM description: Screenshot name: Important screenshot tags: values: - screenshot status: draft required: - resource - name: md5 in: query description: >- Provide the Base64 encoded MD5 checksum of the resource. This is only used when creating the asset and resource simultaneously. required: false type: string - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv - name: analyze in: query description: >- Set the analyze parameter to true to enable the AI tag analysis. Analysis will only occur for managed assets. required: false type: boolean - name: autocurate in: query description: >- Set the autocurate parameter to true automatically curate and accept all suggested tags. required: false type: boolean - name: x-ibm-dx-publish-priority in: header type: string format: string enum: - now - next description: >- Specify `now` to bypass the publishing schedule. Specify `next` to use publishing schedule. responses: '201': description: Successfully created a new asset. schema: *ref_6 '400': description: >- The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly. schema: *ref_0 '409': description: An asset already exists with the given ID. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/assets/{id}': get: tags: - Authoring assets summary: Retrieve an existing asset. description: >- 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 produces: - application/json parameters: - name: id in: path description: Provide the ID of the asset that you want to retrieve. required: true type: string - name: If-None-Match in: header type: string description: >- Provide the double quoted revision of the asset. If this value matches the newest version, a 304 Not Modified response will be returned. required: false - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv responses: '200': description: >- Successfully retrieved an existing asset that matches the ID that you provided. schema: *ref_6 '304': description: >- The Etag provided in the If-None-Match header corresponds to the latest version. '404': description: The asset with the provided id was not found. schema: *ref_0 '412': description: >- The Etag provided in the If-None-Match header does not correspond to the latest version. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer delete: tags: - Authoring assets summary: Delete an existing asset. description: >- Use this endpoint to immediately delete an existing asset from the database.
User roles: admin, manager, editor produces: - application/json parameters: - name: id in: path description: Provide the ID of the asset that you want to delete. required: true type: string - name: If-Match in: header type: string description: >- Provide an Etag value from a previous request to check when an asset was last updated. If the Etag value that you provide is old, the call returns a 412 with the latest version of the asset. required: false responses: '204': description: >- Successfully deleted the asset that matches the ID that you provided. '404': description: The asset with the provided id was not found. schema: *ref_0 '409': description: >- The Etag provided in the If-Match header does not correspond to the latest version. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor put: tags: - Authoring assets summary: Update an existing asset. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: id in: path description: Provide the ID of the asset that you want to update. required: true type: string - name: asset in: body description: >- Provide all the data that you want to update in this asset. The resource data that you provided is validated. If you change the resource of the asset with a new resource, it must not cause any changes to the asset. The path that you provide must contain a leading slash and must be unique and unchanged. The path and name fields are optional and are generated from the resource’s name by default. required: true schema: type: object properties: resource: type: string name: type: string path: type: string description: type: string tags: type: array items: type: string categoryIds: type: array items: type: string example: resource: 8d21025d21e7b3595cbf630fb9d7212b path: /Screen Shot 2016-05-11 at 6.52.22 PM description: Screenshot tags: values: - screenshot required: - resource - name: If-Match in: header type: string description: >- Provide an Etag value from a previous request to check if the asset is the latest. If the value that you provided is old, a 412 Precondition Failed response will be returned. required: false - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv - name: forceOverride in: query description: Specifies whether revision checking should be disabled. type: boolean default: false required: false - name: x-ibm-dx-publish-priority in: header type: string format: string enum: - now - next description: >- Specify `now` to bypass the publishing schedule. Specify `next` to use publishing schedule. responses: '200': description: >- Successfully updated the asset that matches the ID that you provided. schema: *ref_6 '400': description: >- The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly. schema: *ref_0 '409': description: >- The asset was updated by another user whilst you tried to update it. Please review the latest version before retrying. schema: *ref_0 '412': description: >- The Etag provided in the If-Match header does not correspond to the latest version. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/assets/record: get: tags: - Authoring assets summary: Retrieve an existing asset by path. description: >- 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 produces: - application/json parameters: - name: path in: query description: Provide the path of the asset that you want to retrieve. required: true type: string - name: If-None-Match in: header type: string description: >- Provide the double quoted revision of the asset. If this value matches the newest version, a 304 Not Modified response will be returned. required: false - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv responses: '200': description: >- Successfully retrieved an existing asset that matches the path that you provided. schema: *ref_6 '304': description: >- The Etag provided in the If-None-Match header corresponds to the latest version. '400': description: The path provided was not valid. schema: *ref_0 '404': description: The asset with the provided path was not found. schema: *ref_0 '412': description: >- The Etag provided in the If-None-Match header does not correspond to the latest version. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/assets/{id}/analyze': post: summary: >- AI analyzes the asset. The analysis results are stored on the asset itself. description: >- Use the /assets/{id}/analyze endpoint to perform AI analysis on asset if supported.
User roles: admin, manager, editor parameters: - name: id in: path description: >- Provide the ID of the asset item that you need to perform AI analytics. type: string required: true - name: autocurate in: query description: >- Set the autocurate parameter to true automatically curate and accept all suggested tags. required: false type: boolean tags: - Authoring assets responses: '200': description: The asset after getting updated with AI analysis results. schema: *ref_6 '400': description: The analysis of this asset is not supported. schema: *ref_0 '404': description: 'The asset item with ID {id} was not found.' schema: *ref_0 '429': *ref_165 default: description: Unexpected error. schema: *ref_0 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/assets/{id}/create-draft': post: summary: Create a draft of existing asset. description: >- Use this endpoint to create draft of existing asset and return the draft if successful.
User roles: admin, manager, editor parameters: - name: id in: path description: Provide the ID of the asset item that you need to create draft of. type: string required: true - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string collectionFormat: csv - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv tags: - Authoring assets responses: '201': description: Successfully created a new asset draft of given asset. schema: *ref_6 '400': description: The draft creation on provided asset is not supported. schema: *ref_0 '404': description: 'The asset item with ID {id} was not found.' schema: *ref_0 '429': *ref_165 default: description: Unexpected error. schema: *ref_0 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/assets/views/by-modified: get: summary: Retrieve all assets modified within the specified date description: >- 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 produces: - application/json parameters: - name: start in: query description: >- Provide the date and time of when the last modifications were made to the asset that you want returned. The assets that were modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: end in: query description: >- Provide the date and time of when the last modifications were made to the asset that you want returned. The assets that were modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: offset in: query description: >- Use the offset parameter to specify the number of assets to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of assets to return in a single result. default: 50 required: false type: integer - name: order in: query description: >- Specify whether you want the assets to be returned in ascending or descending order. Assets are returned in descending order by default. required: false default: descending type: string enum: - descending - ascending - name: fields in: query description: >- Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Optional: Parameters used to include additional fields inside each returned asset. Use "links" to include the links section, which contains URLs for actions that can be performed on the asset. Use "metadata" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, "include=links,metadata". required: false type: array items: type: string tags: - Authoring assets responses: '200': description: >- Successfully lists a paged result view of all assets that was modified within the date range specified. schema: *ref_162 '400': description: >- The provided parameters are invalid. Please read the error message and alter the request accordingly. schema: *ref_0 '429': *ref_165 '503': *ref_163 default: *ref_164 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/categories: get: tags: - Authoring categories summary: Retrieve all the taxonomies. description: >- Retrieve all the taxonomies (root categories).
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest. type: number format: integer required: false - name: limit in: query description: >- Set the limit for the maximum number of content items to return in a single result. The default value is 50. type: number format: integer required: false produces: - application/json responses: '200': description: The taxonomies were successfully retrieved. schema: *ref_166 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer post: tags: - Authoring categories summary: Create a new category. description: >- Create a category with the contents of the JSON body.
User roles: admin, manager consumes: - application/json produces: - application/json parameters: - name: body in: body required: true description: The JSON data that is used to create the category. schema: *ref_167 responses: '201': description: The category was successfully created. schema: *ref_8 '400': description: 'The JSON body is either missing fields, or contains invalid fields.' schema: *ref_168 '409': description: A category with the same path exists. schema: *ref_168 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager '/authoring/v1/categories/{id}': get: tags: - Authoring categories summary: Retrieve an existing category item. description: >- Retrieve the category with ID {id}.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: id in: path type: string required: true description: The ID of the category to retrieve. responses: '200': description: The category was successfully retrieved. schema: *ref_8 '404': description: 'The category with ID {id} was not found.' schema: *ref_168 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: tags: - Authoring categories summary: Update an existing category item. description: 'Update the category with ID {id}.
User roles: admin, manager' consumes: - application/json produces: - application/json parameters: - name: id in: path type: string required: true description: The ID of the category to update. - name: body in: body schema: *ref_167 responses: '200': description: The category was successfully updated. schema: *ref_8 '400': description: >- Missing or invalid fields in the JSON body or an invalid revision was supplied. schema: *ref_168 '404': description: >- The category with ID {id} or the parent ID in the JSON body was not found. schema: *ref_168 '409': description: A category with the same path exists. schema: *ref_168 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager delete: tags: - Authoring categories summary: Delete an existing category item. description: >- Delete the category with ID {id} along with all the categories under it.
User roles: admin, manager produces: - application/json parameters: - name: id in: path type: string required: true description: The ID of the category to delete. responses: '200': description: The category was successfully deleted. schema: type: array items: type: object properties: id: type: string description: The ID of the deleted category. rev: type: string description: The revision of the deleted category. '400': description: 'The revision {rev} supplied was invalid.' schema: *ref_168 '404': description: 'The category with ID {id} was not found.' schema: *ref_168 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager /authoring/v1/categories/views/by-modified: get: tags: - Authoring categories summary: Gets all categories modified between the start and end date. description: >- 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 parameters: - name: start in: query description: >- Provide the date and time when the last modifications were made to the category items that you want returned. The category items that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: end in: query description: >- Provide the date and time when the last modifications were made to the category items that you want returned. The category items that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: fields in: query description: >- Only the category items fields that are specified here are returned for each result. Any category item field is a valid value and can be specified as a comma-separated list. For example, to list the category item fields name and ID, provide the value ID, and name. All category item fields are returned by default. required: false type: string - name: offset in: query description: >- Use the offset parameter to specify the number of category items to skip from the beginning of the list and return the rest. required: false type: number format: integer - name: limit in: query description: >- Set the limit for the maximum number of category items to return in a single result. The default value is 50. required: false type: number format: integer - name: order in: query description: >- Specify whether you want the category items to be returned in ascending or descending order. Documents are returned in descending order by default. required: false type: string responses: '200': description: List of category items. schema: *ref_166 '429': *ref_165 '503': description: The service is unable to complete the request. schema: *ref_168 default: description: Unexpected error. schema: *ref_168 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/categories/{id}/children': get: tags: - Authoring categories summary: 'Retrieve the child categories of the category with ID {id}.' description: >- Retrieve the child categories of the category with ID {id}.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: id in: path type: string required: true description: The ID of the category whose children to retrieve. - name: recurse in: query type: boolean required: false description: >- Set to true to recursively retrieve all the sub-categories of the children as well. responses: '200': description: The child categories were successfully retrieved. schema: *ref_166 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v2/categories/{id}/children': get: tags: - Authoring categories summary: 'Retrieve the child categories of the category with ID {id}.' description: >- Retrieve the child categories of the category with ID {id}.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: id in: path type: string required: true description: The ID of the category whose children to retrieve. - name: depth in: query type: integer required: false default: 1 description: >- How many levels of children to get. Defaults to 1. -1 means to get all children. - name: sort in: query type: string required: false description: >- Sort order. Only effective when depth=1. Default sort order is by Depth-First ordered by Name. responses: '200': description: The child categories were successfully retrieved. schema: *ref_166 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v2/categories: get: tags: - Authoring categories summary: Retrieve all the taxonomies and their children. description: >- Retrieve all the taxonomies and their children. Optional depth query string limits the depth of the categories returned.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest. type: number format: integer required: false - name: limit in: query description: >- Set the limit for the maximum number of content items to return in a single result. The default value is 50. type: number format: integer required: false - name: depth in: query description: >- Used to specify the depth of the children to return. 1 -7 returns the given depth. Values above 7 or no value result in all categories. type: number format: integer required: false responses: '200': description: The child categories were successfully retrieved. schema: *ref_169 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/changes/status/ready: post: summary: Mark items as ready for publishing in bulk. description: >- 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 parameters: - name: body in: body description: >- Provide the items for which you want to change the status with bulk ready. required: true schema: *ref_170 tags: - Authoring changes responses: '200': description: >- See the status field to determine whether the request was successful. schema: *ref_171 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/changes/status/retire: post: summary: Bulk retire items. description: >- 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 parameters: - name: body in: body description: >- Provide the items that you want to change to the retire state with bulk retire. required: true schema: *ref_170 tags: - Authoring changes responses: '200': description: >- See the status field to determine whether the request was successful. schema: *ref_171 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/changes/delete: post: summary: Beta - Bulk delete items. description: >- 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 parameters: - name: body in: body description: Provide the items that you want to bulk delete. required: true schema: *ref_173 responses: '200': description: >- The request succeeded, however not all items may have been deleted. The `status` field should be checked for more information. '400': description: Bad request. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 tags: - Authoring changes x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/changes/set-library: post: summary: Beta - Bulk move items to another library. description: >- 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 parameters: - name: body in: body description: Provide the items that you want to bulk move. required: true schema: *ref_174 responses: '200': description: >- The request succeeded, however not all items may have been deleted. The `status` field should be checked for more information. '400': description: Bad request. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 tags: - Authoring changes x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/changes/{uid}/status/ready': post: summary: Mark the item with the specified unique ID as ready for publishing. description: >- 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 parameters: - name: uid in: path description: >- Provide the unique ID of the item that you want to mark as ready for publishing. type: string required: true - name: rev in: query description: Optional. Define the revision of item. type: string tags: - Authoring changes responses: '200': description: >- Item was successfully readied. The item is returned in the response body. '400': description: >- The specified item cannot be changed to ready state from its current state or the request made was invalid. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/changes/{uid}/status/retire': post: summary: Retire an item with the specified unique ID. description: >- 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 parameters: - name: uid in: path description: Provide the unique ID of the item that you want to retire. type: string required: true - name: rev in: query description: Optional.Define the revision of item. type: string tags: - Authoring changes responses: '200': description: >- Item was successfully retired. The item is returned in the response body. '400': description: >- Unable to retire the specified item in its current state or the request made was invalid. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/changes/{classification}/{id}/status/ready': post: summary: >- Mark an item with the specified classification and ID as ready for publishing. description: >- 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 parameters: - name: id in: path description: >- Provide the ID of the item that you want to mark as ready for publishing. type: string required: true - name: classification in: path description: >- Provide the classification of the item that you want to mark as ready for publishing. type: string required: true - name: rev in: query description: Optional. Define the revision of the item. type: string tags: - Authoring changes responses: '200': description: >- Item was succesfully readied. The item is returned in the response body. '400': description: >- The specified item cannot be changed to ready state from its current state or the request made was invalid. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/changes/{classification}/{id}/status/retire': post: summary: Retire an item with the specified classification and ID. description: >- 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 parameters: - name: id in: path description: Provide the ID of the item that you want to retire. type: string required: true - name: classification in: path description: Provide the classificaiton of the item that you want to retire. type: string required: true - name: rev in: query description: Optional. Define the revision of item. type: string tags: - Authoring changes responses: '200': description: >- Item was succesfully retired. The item is returned in the response body. '400': description: >- Unable to retire the specified item in its current state or the request made was invalid. schema: *ref_172 '429': *ref_165 '503': description: The service is currently unavailable. Try again later. schema: *ref_172 default: description: Unexpected error. schema: *ref_172 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/comments: post: tags: - Authoring comments summary: Create a comment. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: body in: body description: Provide the comment message and target to create a comment. required: true schema: *ref_175 responses: '201': description: Successfully created a comment for an item. schema: *ref_12 '400': description: >- The required parameters are missing or invalid. Provide valid parameters to create a comment. schema: *ref_13 '429': *ref_165 '503': description: >- Unable to create the comment as the service is unavailable. Try again later. schema: *ref_13 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/comments/{id}': get: tags: - Authoring comments summary: Retrieve an existing comment. description: >- 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 produces: - application/json parameters: - name: id in: path description: Provide the ID of the comment that you want to retrieve. required: true type: string - name: fields in: query description: >- Only the comment properties that are specified here are returned for each result. Any comment property is a valid value and can be specified in a comma-separated list. For example, to show only the comment properties message and creatorId, provide the values of message and creatorId. All comment properties are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv responses: '200': description: >- Successfully retrieved the comment that matches the ID you specified. schema: *ref_12 '404': description: A comment that matches the ID you specified was not found. schema: *ref_13 '429': *ref_165 '503': description: >- Unable to retrieve the comment from the database as the service is unavailable. Try again later. schema: *ref_13 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: tags: - Authoring comments summary: Update an existing comment. description: >- Use the /comments/{id} end point to update an existing comment that matches the ID that is specified.
User roles: admin, manager, editor consumes: - application/json produces: - application/json parameters: - name: id in: path description: Provide the ID of the comment that you want to update. required: true type: string - name: fields in: query description: >- Only the comment properties that are specified here are returned for each result. Any comment property is a valid value and can be specified in a comma-separated list. For example, to show only the comment properties message and creatorId, provide the values of message and creatorId. All comment properties are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: body in: body description: Provide the comment revision and message to update a comment. required: true schema: *ref_177 responses: '200': description: Successfully updated the comment that matches the ID specified. schema: *ref_12 '400': description: >- The required parameters are missing or invalid. Provide valid parameters to update the comment. schema: *ref_13 '404': description: A comment that matches the ID specified was not found. schema: *ref_13 '409': description: >- The comment was updated by another user while you tried to update it. Review the recent version before retrying. schema: *ref_13 '429': *ref_165 '503': description: >- Unable to retrieve the comment from the database as the service is unavailable. Try again later. schema: *ref_13 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor delete: tags: - Authoring comments summary: Delete an existing comment. description: >- Use the /comments/{id} endpoint to delete an existing comment from the database.
User roles: admin, manager, editor produces: - application/json parameters: - name: id in: path description: Provide the ID of the comment that you want to delete. required: true type: string responses: '204': description: The comment was deleted succesfully. '404': description: A comment that matches the ID specified was not found. schema: *ref_13 '429': *ref_165 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/comments/by-item/{classification}/{id}': get: summary: Retrieve all comments for a specific item. description: >- 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 produces: - application/json parameters: - name: classification in: path description: >- Provide the classification of the item for which you want to retrieve the comments. required: true type: string format: string - name: id in: path description: Provide ID of the item for which you want to retrieve the comments. required: true type: string format: string - name: since in: query description: >- Provide the date from when to retrieve comments. Only comments that were added after this date are retrieved. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: offset in: query description: >- Use the offset parameter to specify the number of comments to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of comments to return in a single result. The maximum number of comments that are returned by default is 50. default: 50 required: false type: integer - name: order in: query description: >- Specify whether you want the comments to be returned in ascending or descending order. Comments are returned in descending order by default. required: false default: descending type: string enum: - descending - ascending - name: fields in: query description: >- Only the comment properties that are specified here are returned for each result. Any comment property is a valid value and can be specified in a comma-separated list. For example, to show only the comment properties message and creatorId, provide the values of message and creatorId. All comment properties are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv tags: - Authoring comments responses: '200': description: >- Successfully lists a paged result view of all comments for the given item, optionally filtered by date. schema: *ref_178 '304': description: >- The Etag value that is provided in the If-None-Match header corresponds to the recent version. '429': *ref_165 '503': description: >- Unable to list the comments in the database as the service is unavailable. Try again later. schema: *ref_13 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/comments/by-user/{userId}': get: summary: Retrieve all comments that were created by a user. description: >- 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 produces: - application/json parameters: - name: userId in: path description: Provide the ID of the user that created the comment. required: true type: string format: string - name: since in: query description: >- Retrieve only comments newer than this date. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: offset in: query description: >- Use the offset parameter to specify the number of comments to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of comments to return in a single result. The maximum number of comments that are returned by default is 50. default: 50 required: false type: integer - name: order in: query description: >- Specify whether you want the comments to be returned in ascending or descending order. Comments are returned in descending order by default. required: false default: descending type: string enum: - descending - ascending - name: fields in: query description: >- Only the comment properties that are specified here are returned for each result. Any comment property is a valid value and can be specified in a comma-separated list. For example, to show only the comment properties message and creatorId, provide the values of message and creatorId. All comment properties are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv tags: - Authoring comments responses: '200': description: >- Successfully lists a paged result view of all comments for the specified userId, optionally filtered by date. schema: *ref_178 '429': *ref_165 '503': description: >- Unable to list the comments in the database as the service is unavailable. Try again later. schema: *ref_13 default: *ref_176 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/content: get: summary: List all content items in the database. description: |- Use the /content endpoint to list all content items in the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest. required: false type: number format: integer - name: fields in: query description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. required: false type: string - name: limit in: query description: >- Set the limit for the maximum number of content items to return in a single result. The default value is 50. required: false type: number format: integer tags: - Authoring content responses: '200': description: >- Successfully lists a paged result view of all content items in the database. schema: *ref_179 '429': *ref_165 '503': description: >- Unable to list the content items in the database as the service is currently unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer post: summary: Create content items. description: >- 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 parameters: - name: body in: body description: >- Provide the content item fields such as name, typeId, status and tags. The name and typeId fields are required. required: true schema: *ref_181 - name: x-ibm-dx-publish-priority in: header type: string format: string enum: - now - next description: >- Specify `now` to bypass the publishing schedule. Specify `next` to use publishing schedule. tags: - Authoring content responses: '201': description: Successfully created a content item with the specified content type. schema: *ref_15 headers: x-ibm-dx-validation-warnings: description: >- The number of validation warnings that occurred. Use the /content/{id}/validate endpoint for a full list of any warnings. type: integer '400': description: >- The body parameter is empty or has an invalid input. Provide valid type fields that are required to create the new content item. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to create the content item as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/content/{id}': get: summary: Retrieve an existing content item. description: >- 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 parameters: - name: id in: path description: Provide the ID of the content item that you want to retrieve. type: string required: true - name: include in: query description: >- Optional. Parameters used to include additional fields inside each returned content item. Use "links" to include the links section, which contains URLs for actions that can be performed on the content item. Use "metadata" to include additional fields for each of the items referenced by the content item, such as the URL of the referenced assets. You can specify multiple fields as a comma-separated value. For example, "include=links, metadata". type: string - name: fields in: query description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. required: false type: string tags: - Authoring content responses: '200': description: >- Successfully retrieved the API representation for the existing content item that matches the ID that you provided. schema: *ref_15 '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '429': *ref_165 '503': description: >- Unable to retrieve the content item from the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: summary: Update an existing content item. description: >- Use the /content/{id} endpoint 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 parameters: - name: id in: path description: Provide the ID of the content item that you want to update. type: string required: true - name: body in: body description: >- Provide the body fields such as name, typeId, tags, and data of the content item that you want to update. If you do not provide any information, the content item will not be updated before it is moved to the published stage. The current revision must be provided in order to update the content. required: false schema: *ref_182 - name: include in: query description: >- Optional. Parameters used to include additional fields inside each returned content item. Use "links" to include the links section, which contains URLs for actions that can be performed on the content item. Use "metadata" to include additional fields for each of the items referenced by the content item, such as the URL of the referenced assets. You can specify multiple fields as a comma-separated value. For example, "include=links, metadata". type: string - name: fields in: query description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. required: false type: string - name: forceOverride in: query description: >- Force this update over the existing content item. When set to true, this request will overwrite the stored content, regardless of a difference in revisions (ignoring or reverting changes that were made since the item was last retrieved). required: false type: boolean - name: x-ibm-dx-publish-priority in: header type: string format: string enum: - now - next description: >- Specify `now` to bypass the publishing schedule. Specify `next` to use publishing schedule. tags: - Authoring content responses: '200': description: >- Successfully updated the content item that matches the ID that you provided. schema: *ref_15 headers: x-ibm-dx-validation-warnings: description: >- The number of validation warnings that occurred. Use the /content/{id}/validate endpoint for a full list of any warnings. type: integer '400': description: The update request is invalid or the request failed validation. schema: *ref_180 '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '409': description: >- Unable to update the content item with the ID {id} because another user updated the content item since it was last retrieved. Retrieve the content item again and reapply your changes. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to retrieve the content item from the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor delete: summary: Delete an existing content item immediately. description: >- 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 parameters: - name: id in: path description: Provide the ID of the content item that you want to delete. type: string required: true tags: - Authoring content responses: '200': description: >- Successfully deleted the content item that matches the ID that you provided. '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '409': description: >- Unable to delete the content item with the ID "{0}" because another user updated the content item since it was last retrieved. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to delete the content item in the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/content/{id}/unpublish': post: summary: Unpublish a published item. description: >- Use the /content/{id}/unpublish endpoint to unpublish an existing published content item in the database.
User roles: admin, manager, editor parameters: - name: id in: path description: Provide the ID of the content item to unpublish. type: string required: true tags: - Authoring content responses: '200': description: Successfully unpublished the item. schema: *ref_15 headers: x-ibm-dx-validation-warnings: description: >- The number of validation warnings that occurred. Use the /content/{id}/validate endpoint for a full list of any warnings. type: integer '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '409': description: >- Unable to unpublish the content item with the ID "{0}" because another user updated the content item since it was last retrieved. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to unpublish the content item in the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/content/views/by-type: get: summary: Retrieve all content of the specified type. description: >- 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 parameters: - name: id in: query description: >- Provide the ID of the content type by which you want to filter the content items. required: true type: string - name: fields in: query description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. required: false type: string - name: offset in: query description: >- Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest. required: false type: number format: integer - name: limit in: query description: >- Set the limit for the maximum number of content items to return in a single result. The default value is 50. required: false type: number format: integer tags: - Authoring content responses: '200': description: >- Successfully lists a paged result view of all content items of a specified content type. schema: *ref_179 '429': *ref_165 '503': description: >- Unable to list the content items in the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/content/views/by-modified: get: summary: Retrieve all content modified within the specified date. description: >- Use the /content/views/by-modified endpoint to retrieve all content items that were modified within the date range specified.
User roles: admin, manager, editor, viewer parameters: - name: start in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the content items that you want returned. The content items that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: end in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the content items that you want returned. The content items that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: startId in: query required: false type: string description: >- If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. Note: when reversing the order you do not switch start and end IDs. - name: endId in: query required: false type: string description: >- If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. Note: when reversing the order you do not switch start and end IDs. - name: limit in: query required: false type: number format: integer description: >- Set the limit for the maximum number of content items to return in a single result. The default value is 50. You can pass 0 to unset the limit and stream all available results. A streaming parser can be avoided with format=sequence. - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: offset in: query required: false type: number format: integer description: >- Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest. Note: large offsets perform poorly. Use start keys to index into large result sets. Also see pageMode. - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backward, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: fields in: query required: false type: string description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. - name: order in: query required: false type: string enum: - ascending - descending description: > Specify the order of the results. * `ascending` - (default) result keys are increasing * `descending` - result keys are decreasing It is not necessary to switch the start and end keys and IDs when reversing the order. tags: - Authoring content responses: '200': description: >- Successfully lists a paged result view of all content items that were modified within the date range specified. schema: *ref_179 '401': description: >- You do not have authorization to retrieve the content items from the database. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to list the content items in the database as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/content/{id}/create-draft': post: summary: Create a draft version of an existing content item. description: >- 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 parameters: - name: id in: path description: >- Provide the ID of the content item that you want to create a draft version. type: string required: true - name: If-Match in: header description: >- Provide a revision value from a previous request to check when a content item was last updated. If the value that you provide is old, the call returns a 412 with the latest version of the content item. type: string - name: include in: query description: >- Optional. Parameters used to include additional fields inside each returned content item. Use "links" to include the links section, which contains URLs for actions that can be performed on the content item. Use "metadata" to include additional fields for each of the items referenced by the content item, such as the URL of the referenced assets. You can specify multiple fields as a comma-separated value. For example, "include=links, metadata". type: string - name: fields in: query description: >- Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default. required: false type: string tags: - Authoring content responses: '200': description: Successfully created a draft version of the content item. schema: *ref_15 '400': description: >- The content item is not in the ready state and cannot create a draft. schema: *ref_180 '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '409': description: >- A draft already exists with the given ID or unable to create a draft of the content item as it was updated by another user since you retrieved it. schema: *ref_180 '412': description: >- The If-Match pre-condition failed. The revision value that you provided in the If-Match parameter did not match the recent document version. The error message includes the recent version of the document. schema: *ref_15 '429': *ref_165 '503': description: >- Unable to change the status of the content item as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/content/count: get: summary: Retrieve the total number of content items in the database. tags: - Authoring content responses: '200': description: >- Successfully returns the count of the total number of content items in the database. schema: *ref_183 '429': *ref_165 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer description: '
User roles: admin, manager, editor, viewer' '/authoring/v1/content/{id}/analyze': post: summary: AI analyzes and provides tag recommendations for the content. description: >- Use the /content/{id}/analyze endpoint to perform AI analysis on content text.
User roles: admin, manager, editor parameters: - name: id in: path description: >- Provide the ID of the content item that you need to perform AI analytics. type: string required: true tags: - Authoring content responses: '200': description: Successfully retrieved cognitive tags for content text. schema: *ref_184 '400': description: The content locale is not supported by AI Text API. schema: *ref_180 '404': description: 'The content item with ID {id} was not found.' schema: *ref_180 '429': *ref_165 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/content/{id}/validate': post: summary: Validate the specified content item against its type. description: >- Use the /content/{id}/validate endpoint to validate if the content item specified matches its recorded content type.
User roles: admin, manager, editor parameters: - name: id in: path description: Provide the ID of the content document that you want to validate. type: string required: true tags: - Authoring content responses: '200': description: >- Completed the validation, which failed for this content item. See the results to find out what validation errors occurred. schema: *ref_185 '204': description: Successfully completed the validation; validation passed. '400': description: 'The ID that you provided is invalid, provide a valid ID.' schema: *ref_180 '401': description: You do not have authorization to validate this content item. schema: *ref_180 '404': description: >- A content item with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_180 '429': *ref_165 '503': description: >- Unable to validate the content item as the service is unavailable. Try again later. schema: *ref_180 default: description: Unexpected error. schema: *ref_180 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/copy/sync: post: tags: - Authoring Import summary: Copies the specified documents. x-ibm-dx-security-user-roles: - admin - manager description: >- 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 parameters: - name: body in: body description: The list of documents to copy required: true schema: *ref_186 - name: referencesToClear in: query description: > Optional comma separated list of reference types to clear within copied documents. Supported values: `asset`, `content`, `category`, `image-profile` type: string required: false - name: referencesToClone in: query description: > Optional comma separated list of reference types to copy (when referenceLevels > 0). Defaults to the reference types of the initial items to copy. Supported values: asset, content type: string required: false - name: referenceLevels in: query description: >- The number of reference levels to copy. Defaults to 0, meaning to copy only the specified items. type: number required: false - name: clearElementsOnLastLevel in: query description: > Specifies whether the elements on the last level of references should have their elements cleared. Has no effect when referencesLevels is not greater than zero. type: boolean - name: x-ibm-dx-publish-priority in: header type: string format: string enum: - now description: Specify `now` to bypass the publishing schedule. responses: '200': description: Results of the copy operation. schema: *ref_187 '400': description: >- Tenant header (x-ibm-dx-tenant-id) not specified OR Tenant not found OR copy items belong to different projects. '429': *ref_165 '500': description: Unexpected error. schema: *ref_188 /authoring/v1/layouts: post: tags: - Authoring layouts summary: Create new layouts. description: >- Use the /layouts end-point to create a new layout.
User roles: admin, manager parameters: - name: body in: body description: Contains the layout to create. required: true schema: *ref_189 responses: '201': description: Success. schema: *ref_22 '400': description: Empty body or Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: Current tenant's database is not provisioned. schema: *ref_190 '409': description: Layout with the same path exists. '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring layouts summary: Retrieve all layouts in the database. description: >- Use the /layouts endpoint to retrieve all layouts from the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of layouts to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layouts that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the layouts to be returned in ascending/alphabetical (default) or descending/reverse-alphabetical order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the layout fields that are specified here are returned for each result. Any layout field is a valid value and can be specified as a comma-separated list. type: string required: false responses: '200': description: Success. schema: *ref_191 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/layouts/by-content/{content-id}': get: tags: - Authoring layouts summary: Retrieves the layouts associated with the specified content. description: >- 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 parameters: - name: content-id in: path description: The ID of the content whose associated layouts should be returned. type: string required: true - name: projectId in: query description: > Optionally specifies the context for draft overlay. Contains the project id, or special values: * draft for standalone draft overlays * none for no project overlay. When both the 'projectId' query-string parameter AND the 'x-ibm-dx-project-id' header are specified, the 'projectId' query-string parameter will override the 'x-ibm-dx-project-id' header. type: string required: false - name: filter in: query description: | An optional filter to control the returned results. Valid options are: * selected: Indicates that only the selected layout should be returned. type: string required: false - name: offset in: query description: >- Use the offset parameter to specify the number of layouts to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layouts that are returned. type: number format: integer default: 50 required: false - name: fields in: query description: >- Only the layout fields that are specified here are returned for each result. Any layout field is a valid value and can be specified as a comma-separated list. type: string required: false - name: x-ibm-dx-project-id in: header description: > Optionally specifies the context for draft overlay. Contains the project id, or special values: * draft for standalone draft overlays * none for no project overlay. When both the 'projectId' query-string parameter AND the 'x-ibm-dx-project-id' header are specified, the 'projectId' query-string parameter will override the 'x-ibm-dx-project-id' header. required: false type: string responses: '200': description: Success. schema: *ref_192 '400': description: Invalid ID OR Invalid input. schema: *ref_190 '404': description: >- The content with ID {contentId} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layouts/by-path: get: tags: - Authoring layouts summary: Retrieve an existing layout by its path. description: >- Use the /layouts/by-path end-point to retrieve an existing layout from the database.
User roles: admin, manager, editor, viewer parameters: - name: path in: query description: The path of the layout to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any layout field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator and last modifier to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the layout retrieved is the most recent version. If the layout is the most recent version, the call returns a 304 ( Not modified) message instead of sending the layout back. type: string required: false responses: '200': description: Success. schema: *ref_22 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid path OR Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with path {path} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layouts/count: get: tags: - Authoring layouts summary: Retrieve the total number of layouts. description: >- Use the /layouts/count endpoint to obtain the total number of layouts within the database.
User roles: admin, manager, editor, viewer responses: '200': description: layout count schema: *ref_193 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/layouts/{id}': put: tags: - Authoring layouts summary: Update an existing layout. description: >- Use the /layouts/{id} end-point to update an existing layout within the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the layout document to update. type: string required: true - name: forceOverride in: query description: Specifies whether revision checking should be disabled. type: boolean default: false required: false - name: body in: body description: Contains the updated layout object to save. required: true schema: *ref_22 responses: '200': description: Success. schema: *ref_22 '400': description: Invalid ID or Invalid input. schema: *ref_190 '401': description: The user is not authorized to run this action. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '409': description: >- Another user updated the document since it was last retrieved OR when changing the path, there is an existing document at that path. schema: *ref_190 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager delete: tags: - Authoring layouts summary: Delete an existing layout. description: >- Use the /layouts/{id} endpoint to delete an existing layout from the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the layout to delete. type: string required: true responses: '200': description: Success. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '401': description: The user is not authorized to run this action. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring layouts summary: Retrieve an existing layout. description: >- Use the /layouts/{id} end-point to retrieve an existing layout from the database.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: The ID of the layout to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any layout field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator and last modifier to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the layout retrieved is the most recent version. If the layout is the most recent version, the call returns a 304 ( Not modified) message instead of sending the layout back. type: string required: false responses: '200': description: Success. schema: *ref_22 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layouts/views/by-modified: get: tags: - Authoring layouts summary: Retrieve all layouts in the database ordered by last modified date. description: >- 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 parameters: - name: start in: query description: > Provide the date and time of when the last modifications were made to the layouts that you want returned. When the order is ascending (default), the layouts that are modified on or after this date and time are returned. When the order is descending, the layouts that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: end in: query description: > Provide the date and time of when the last modifications were made to the layouts that you want returned. When the order is ascending (default), the layouts that are modified on or before this date and time are returned. When the order is descending, the layouts that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: startId in: query required: false type: string description: > If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. - name: endId in: query required: false type: string description: > If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. - name: offset in: query description: >- Use the offset parameter to specify the number of layouts to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layouts that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the layout documents to be returned in ascending/oldest-first (default) or descending/newest-first order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the layout fields that are specified here are returned for each result. Any layout field is a valid value and can be specified as a comma-separated list. type: string required: false responses: '200': description: Success. schema: *ref_191 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layouts/views/by-name: get: tags: - Authoring layouts summary: Retrieve all layouts in the database with the specified name. description: >- Use the /layouts/views/by-name endpoint to retrieve all layouts from the database with the specified name.
User roles: admin, manager, editor, viewer parameters: - name: name in: query description: The name to query. required: true type: string - name: offset in: query description: >- Use the offset parameter to specify the number of layouts to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layouts that are returned. type: number format: integer default: 50 required: false - name: fields in: query description: >- Only the layout fields that are specified here are returned for each result. Any layout field is a valid value and can be specified as a comma-separated list. type: string required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line responses: '200': description: Success. schema: *ref_191 '400': description: Invalid name or Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layout-mappings: post: tags: - Authoring layouts summary: Create new layout mappings. description: >- Use the /layout-mapping end-point to create a new layout mapping.
User roles: admin, manager parameters: - name: body in: body description: Contains the layout mapping to create. required: true schema: *ref_194 responses: '201': description: Success. schema: *ref_24 '400': description: Empty body or Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: Current tenant's database is not provisioned. schema: *ref_190 '409': description: >- A layout mapping associated with the same content-type OR path exists. '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring layouts summary: Retrieve all layout mappings in the database. description: >- Use the /layout-mappings endpoint to retrieve all layout mappings from the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of layout mappings to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layout mappings that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the layout mappings to be returned in ascending (default) or descending order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the layout mapping fields that are specified here are returned for each result. Any layout mapping field is a valid value and can be specified as a comma-separated list. type: string required: false responses: '200': description: Success. schema: *ref_195 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layout-mappings/by-path: get: tags: - Authoring layouts summary: Retrieve an existing layout mapping by its path. description: >- Use the /layout-mappings/by-path end-point to retrieve an existing layout mapping from the database.
User roles: admin, manager, editor, viewer parameters: - name: path in: query description: The path of the layout mapping to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any layout mapping field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator, last modifier and the names of mapped layouts to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the layout mapping retrieved is the most recent version. If the layout mapping is the most recent version, the call returns a 304 ( Not modified) message instead of sending the layout mapping back. type: string required: false responses: '200': description: Success. schema: *ref_24 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid path OR Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with path {path} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/layout-mappings/by-type/{type-id}': get: tags: - Authoring layouts summary: Retrieve an existing layout mapping via its associated content-type. description: >- 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 parameters: - name: type-id in: path description: The ID of the content-type whose layout mapping should be retrieved. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any layout mapping field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator, last modifier and the names of mapped layouts to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the layout mapping retrieved is the most recent version. If the layout mapping is the most recent version, the call returns a 304 ( Not modified) message instead of sending the layout mapping back. type: string required: false responses: '200': description: Success. schema: *ref_24 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '404': description: >- There is no layout-mapping associated with the specified content-type OR Current tenant's database is not provisioned OR the operation is not available based on the current tenant's tier. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer delete: tags: - Authoring layouts summary: Deletes an existing layout mapping via its associated content-type. description: >- Use the /layout-mappings/by-type/{type-id} end-point to delete an existing layout mapping from the database.
User roles: admin, manager parameters: - name: type-id in: path description: The ID of the content-type whose layout mapping should be deleted. type: string required: true responses: '200': description: Success. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- There is no layout-mapping associated with the specified content-type OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager '/authoring/v1/layout-mappings/by-type/{type-id}/copy': post: tags: - Authoring layouts summary: Copies an existing layout mapping via its associated content-type. description: >- 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 parameters: - name: type-id in: path description: The ID of the content-type whose layout mapping should be copied. type: string required: true - name: targetTypeId in: query description: The ID of the content-type to associate with the copy. type: string required: true - name: name in: query description: >- An optional name to associate with the copy. If there is an existing layout mapping with the specified name, then the copied document will have a name in the format 'Copy [NUMBER] of [NAME]' type: string required: false responses: '200': description: >- There was an existing layout mapping found for the specified content-type. schema: *ref_24 '201': description: Successfully copied the layout mapping. schema: *ref_24 '404': description: >- A document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager /authoring/v1/layout-mappings/count: get: tags: - Authoring layouts summary: Retrieve the total number of layout mappings. description: >- Use the /layout-mappings/count endpoint to obtain the total number of layout mappings within the database.
User roles: admin, manager, editor, viewer responses: '200': description: layout mapping count schema: *ref_193 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/layout-mappings/{id}': put: tags: - Authoring layouts summary: Update an existing layout mapping. description: >- Use the /layout-mappings/{id} end-point to update an existing layout mapping within the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the layout mapping document to update. type: string required: true - name: forceOverride in: query description: Specifies whether revision checking should be disabled. type: boolean default: false required: false - name: body in: body description: Contains the updated layout mapping object to save. required: true schema: *ref_24 responses: '200': description: Success. schema: *ref_24 '400': description: Invalid ID or Invalid input. schema: *ref_190 '401': description: The user is not authorized to run this action. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '409': description: >- Another user updated the document since it was last retrieved OR when changing the mapped content-type, there is an existing mapping with the chosen content-type OR when changing the path, there is an existing mapping at that path. schema: *ref_190 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager delete: tags: - Authoring layouts summary: Delete an existing layout mapping. description: >- Use the /layout-mappings/{id} endpoint to delete an existing layout mapping from the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the layout mapping to delete. type: string required: true responses: '200': description: Success. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '401': description: The user is not authorized to run this action. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 '500': description: Unexpected error. schema: *ref_190 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring layouts summary: Retrieve an existing layout mapping. description: >- Use the /layout-mappings/{id} end-point to retrieve an existing layout mapping from the database.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: The ID of the layout mapping to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any layout mapping field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator, last modifier and the names of mapped layouts to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the layout mapping retrieved is the most recent version. If the layout mapping is the most recent version, the call returns a 304 ( Not modified) message instead of sending the layout mapping back. type: string required: false responses: '200': description: Success. schema: *ref_24 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid ID OR Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/layout-mappings/{id}/copy': post: tags: - Authoring layouts summary: Copies an existing layout mapping. description: >- 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 parameters: - name: id in: path description: Provide the ID of the layout mapping that you wish to copy. type: string required: true - name: typeId in: query description: The ID of the content-type to associate with the copy. type: string required: true - name: name in: query description: >- An optional name to associate with the copy. If there is an existing layout mapping with the specified name, then the copied document will have a name in the format 'Copy [NUMBER] of [NAME]' type: string required: false responses: '200': description: >- There was an existing layout mapping found for the specified content-type. schema: *ref_24 '201': description: Successfully copied the layout mapping. schema: *ref_24 '404': description: >- A document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager /authoring/v1/layout-mappings/views/by-modified: get: tags: - Authoring layouts summary: >- Retrieve all layout mappings in the database ordered by last modified date. description: >- 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 parameters: - name: start in: query description: > Provide the date and time of when the last modifications were made to the layout mappings that you want returned. When the order is ascending (default), the layouts that are modified on or after this date and time are returned. When the order is descending, the layouts that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: end in: query description: > Provide the date and time of when the last modifications were made to the layout mappings that you want returned. When the order is ascending (default), the layouts that are modified on or before this date and time are returned. When the order is descending, the layouts that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: startId in: query required: false type: string description: > If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. - name: endId in: query required: false type: string description: > If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. - name: offset in: query description: >- Use the offset parameter to specify the number of layout mappings to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layout mappings that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the layout mapping documents to be returned in ascending/oldest-first (default) or descending/newest-first order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the layout mapping fields that are specified here are returned for each result. Any layout mapping field is a valid value and can be specified as a comma-separated list. type: string required: false responses: '200': description: Success. schema: *ref_195 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/layout-mappings/views/by-name: get: tags: - Authoring layouts summary: Retrieve all layout mappings in the database with the specified name. description: >- 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 parameters: - name: name in: query description: The name to query. required: true type: string - name: offset in: query description: >- Use the offset parameter to specify the number of layout mappings to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of layout mappings that are returned. type: number format: integer default: 50 required: false - name: fields in: query description: >- Only the layout mapping fields that are specified here are returned for each result. Any layout mapping field is a valid value and can be specified as a comma-separated list. type: string required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line responses: '200': description: Success. schema: *ref_195 '400': description: Invalid name or Invalid input. schema: *ref_190 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_190 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/libraries/{id}': get: summary: Get an existing library description: >- Use this endpoint to retrieve an existing library.
User roles: admin, manager, editor, viewer tags: - Authoring library parameters: - name: id in: path description: The ID of the library that you want to retrieve. required: true type: string - name: If-None-Match in: header type: string description: >- Provide the double-quoted revision of the library. If this value matches the newest version, a 304 Not Modified response will be returned. required: false - name: include in: query description: >- Additional library fields that are specified here are returned. Field that can be included is metadata. Fields are to be provided as a comma-separated list. required: false type: array items: type: string collectionFormat: csv responses: '200': description: Successfully retrieved the library. schema: *ref_26 '429': *ref_165 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: summary: Update an existing library description: >- Use this endpoint to update an existing library.
User roles: admin, manager, editor parameters: - name: id in: path description: The ID of the library that you want to update. required: true type: string - name: ignoreUsers in: query required: false type: boolean description: >- Set to true to update the library without changing its owners or contributors, used for importing to and from other subscriptions with different sets of users. False by default. tags: - Authoring library responses: '200': description: Successfully updated the library. schema: *ref_26 '429': *ref_165 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor delete: summary: Delete an existing library description: >- Use this endpoint to delete an existing library.
User roles: admin, manager, editor parameters: - name: id in: path description: The ID of the library that you want to delete. required: true type: string tags: - Authoring library responses: '204': description: Successfully deleted the library. '429': *ref_165 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/libraries: get: summary: Get all the libraries description: >- Use this endpoint to retrieve all libraries.
User roles: admin, manager, editor, viewer parameters: - name: start in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the libraries that you want returned. The libraries that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: end in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the libraries that you want returned. The libraries that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: offset in: query description: >- Use the offset parameter to specify the number of libraries to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of libraries to return in a single result. default: 50 required: false type: integer - name: order in: query description: >- Specify whether you want the libraries to be returned in ascending or descending order. Libraries are returned in descending order by default. required: false default: descending type: string enum: - descending - ascending - name: fields in: query description: >- Only the library fields that are specified here are returned for each result. Any library field is a valid value and these can be specified in a comma-separated list. For example, to list the library fields name and ID, provide the value ID, and name. All library fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv tags: - Authoring library responses: '200': description: >- Successfully lists a paged result view of all libraries that were modified within the date range specified. schema: *ref_197 '401': description: >- You do not have authorization to retrieve the libraries from the database. schema: *ref_196 '429': *ref_165 '503': description: >- Unable to list the libraries in the database as the service is unavailable. Try again later. schema: *ref_196 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer post: summary: Create a new library description: >- Use this endpoint to create a new library.
User roles: admin, manager parameters: - name: ignoreUsers in: query required: false type: boolean description: >- Set to true to create a library with no owners or contributors, used for importing to and from other subscriptions with different sets of users. False by default. tags: - Authoring library responses: '201': description: Indicates successful creation of the library. schema: *ref_198 '429': *ref_165 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager /authoring/v1/libraries/views/by-modified: get: summary: Retrieve all libraries modified within the specified date. description: >- Use the /libraries/views/by-modified endpoint to retrieve all libraries that were modified within the date range specified.
User roles: admin, manager, editor, viewer parameters: - name: start in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the libraries that you want returned. The libraries that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: end in: query required: false type: string format: date-time description: >- Provide the date and time of when the last modifications were made to the libraries that you want returned. The libraries that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: offset in: query description: >- Use the offset parameter to specify the number of libraries to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of libraries to return in a single result. default: 50 required: false type: integer - name: order in: query description: >- Specify whether you want the libraries to be returned in ascending or descending order. Libraries are returned in descending order by default. required: false default: descending type: string enum: - descending - ascending - name: fields in: query description: >- Only the library fields that are specified here are returned for each result. Any library field is a valid value and these can be specified in a comma-separated list. For example, to list the library fields name and ID, provide the value ID, and name. All library fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv tags: - Authoring library responses: '200': description: >- Successfully lists a paged result view of all libraries that were modified within the date range specified. schema: *ref_197 '401': description: >- You do not have authorization to retrieve the libraries from the database. schema: *ref_196 '429': *ref_165 '503': description: >- Unable to list the libraries in the database as the service is unavailable. Try again later. schema: *ref_196 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/libraries/count: get: summary: Retrieve the total number of libraries in the database. tags: - Authoring library responses: '200': description: >- Successfully returns the count of the total number of libraries in the database. schema: *ref_199 '429': *ref_165 default: description: Unexpected error. schema: *ref_196 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer description: '
User roles: admin, manager, editor, viewer' /authoring/v1/references/outgoing: post: tags: - Authoring reference summary: Retrieve the outgoing references for items. description: >- 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 parameters: - name: body in: body description: Provide the request details in the body. required: true schema: *ref_200 consumes: - application/json produces: - application/json responses: '200': description: >- Successfully returns the fetched references. Remember to check the `result.status` property, it can be `ok` or `warn`. If it is `ok`, the query ends normally. Otherwise, the query ends due to a limit but is still able to return an incomplete result set. For example, the query can end due to the current limit for a max depth of recursion of 10 and max total references of 500. schema: *ref_201 '429': *ref_165 default: description: Unexpected error. schema: *ref_202 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/references/outgoing/{classification}/{id}': get: tags: - Authoring reference summary: Retrieve the outgoing references for an item with the provided ID. description: >- 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 parameters: - name: id in: path description: Provide the ID of the item for which you want to fetch references. required: true type: string - name: classification in: path description: >- Provide the classification of the item for which you want to fetch references. required: true type: string - name: filterType in: query description: >- Use the `filterType` parameter to inverse the filters. For example, if you are using `classifications=content-type`, it returns only content-types, however if you add `filterType=exclude` then, it returns everything besides content-types. type: string enum: - include - exclude - name: depth default: 1 in: query description: >- The amount of depth to recursively look for references in an item. The default depth to look for references in an item is 1, so only direct outgoing references are returned. Use a higher amount of depth to get recursive references. Currently, you can request a maximum depth of 10 in one query. The filters like `classifications` and `statuses` can be used to limit amount of data that is returned when you work with references. type: integer - name: classifications description: Classification of items to filter references by. in: query required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: statuses description: >- Provide the workflow status of the item to filter references. If items do not have workflow status, they are normally considered to be in the `ready` state for the purpose of this filtering. in: query required: false allowEmptyValue: true type: array items: type: string enum: - draft - ready - retired collectionFormat: csv - name: include in: query description: >- Use the 'include' parameter to add options to references that you fetch for an item. Currently, the only available option is `metadata`. When you use the `metadata` option in the `include` parameter, the returned code includes metadata about each of the references that are returned. The information that is returned can be controlled by using the `fl` parameter. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: fl in: query description: >- The fields that you can specify in the `fl` parameter are similar to the `fl` query parameters in `/authoring/v1/search` API. You can use the `fl` parameter only if you are also using the `include=metadata` parameter. For example, to retrieve all the document for each of the references use `fl=document`. If the field is not specified, the default fields are returned. The `id` field is always returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv responses: '200': description: >- Successfully returns the fetched references. Remember to check the `result.status`property, it can be `ok` or `warn`. If it is `ok` the query ends normally. Otherwise, the query ends due to a limit but is still able to return an incomplete result set. For example, the query can end due to the current limit for a max depth of recursion of 10 and a max total references of 500. schema: *ref_201 '429': *ref_165 default: description: Unexpected error. schema: *ref_202 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/references/incoming: post: tags: - Authoring reference summary: Retrieve the incoming references for items. description: >- 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 parameters: - name: body in: body description: Provide the request details in the body. required: true schema: *ref_203 consumes: - application/json produces: - application/json responses: '200': description: >- Successfully returns the fetched incoming references for given items. schema: type: object properties: references: type: object additionalProperties: *ref_204 '429': *ref_165 default: description: Unexpected error. schema: *ref_202 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/references/incoming/{classification}/{id}': get: summary: Retrieve the incoming references for an item with the provided ID. description: >- 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 produces: - application/json parameters: - name: id in: path description: >- Provide the ID of the item for which you want to fetch incoming references. required: true type: string - name: classification in: path description: >- Provide the classification of the item for which you want to fetch incoming references. required: true type: string - name: fl in: query description: >- The fields that you can specify in the `fl` parameter are similar to the `fl` query parameters in `/authoring/v1/search` API. You can use the `fl` parameter only if you are also using the `include=metadata` parameter. For example, to retrieve all the document for each of the references use `fl=document`. If the field is not specified, the default fields are returned. The `id` field is always returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Use the 'include' parameter to add options to references that you fetch for an item. Currently, the only available option is `metadata`. When you use the `metadata` option in the `include` parameter, the returned code includes metadata about each of the references that are returned. The information that is returned can be controlled by using the `fl` parameter. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: offset in: query description: >- Use the offset parameter to specify the number of references to skip from the beginning of the list and return the rest. default: 0 required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of references to return in a single result. The current maximum value is 250. default: 50 required: false type: integer tags: - Authoring reference responses: '200': description: Successfully returns the incoming references paged result. schema: *ref_205 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/renditions: get: summary: Retrieve all renditions in the database. description: >- Use this endpoint to list all the renditions in the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of renditions to skip from the beginning of the list and return the rest. required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of renditions to return in a single result. required: false type: integer - name: fields in: query description: >- Only the rendition fields that are specified here are returned for each result. Any renditions field is a valid value and these can be specified in a comma-separated list. For example, to list the renditions fields name and ID, provide the value ID, and name. All renditions fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Additional renditions fields that are specified here are returned. Currently, only the links field can be included. Fields are to be provided as a comma-separated list. required: false type: array items: type: string collectionFormat: csv tags: - Authoring renditions responses: '200': description: >- Successfully lists a paged result view of all the renditions in the database. schema: *ref_206 '429': *ref_165 '503': *ref_207 default: *ref_208 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer post: tags: - Authoring renditions summary: Create a new rendition. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: rendition in: body description: Provide the data to create a rendition. required: true schema: *ref_34 - name: fields in: query description: >- Only the rendition fields that are specified here are returned for each result. Any renditions field is a valid value and these can be specified in a comma-separated list. For example, to list the renditions fields name and ID, provide the value ID, and name. All renditions fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Additional renditions fields that are specified here are returned. Currently, only the links field can be included. Fields are to be provided as a comma-separated list. required: false type: array items: type: string collectionFormat: csv - name: projectId in: query description: >- The id of the project that the rendition's underlying asset resides in. This property must be provided if the asset is in a project. This includes projects with id of "draft". required: false type: string responses: '201': description: Successfully created a new rendition. schema: *ref_37 '400': description: >- The required parameters are missing or invalid, or the number of allowed renditions have been reached. Please read the error message and alter the request accordingly. schema: *ref_1 '409': description: A rendition already exists with the given ID. schema: *ref_1 '429': *ref_165 '503': *ref_207 default: *ref_208 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/renditions/{id}': get: tags: - Authoring renditions summary: Retrieve an existing rendition. description: >- 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 produces: - application/json parameters: - name: id in: path description: Provide the ID of the rendition that you want to retrieve. required: true type: string - name: fields in: query description: >- Only the rendition fields that are specified here are returned for each result. Any renditions field is a valid value and these can be specified in a comma-separated list. For example, to list the renditions fields name and ID, provide the value ID, and name. All renditions fields are returned by default. required: false allowEmptyValue: true type: array items: type: string collectionFormat: csv - name: include in: query description: >- Additional renditions fields that are specified here are returned. Currently, only the links field can be included. Fields are to be provided as a comma-separated list. required: false type: array items: type: string collectionFormat: csv responses: '200': description: Successfully retrieved the rendition. schema: *ref_37 '404': description: The rendition with the provided ID was not found. schema: *ref_1 '429': *ref_165 '503': *ref_207 default: *ref_208 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/renditions/views/by-created: get: summary: Retrieve all renditions created within the specified date range. description: >- Use this endpoint to retrieve all renditions that was created within the date range specified.
User roles: admin, manager, editor, viewer parameters: - name: start in: query description: >- Provide the date and time of when the rendition was created. Renditions that were created on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: end in: query description: >- Provide the date and time of when the rendition was created. Renditions that were created on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. required: false type: string format: date-time - name: fields in: query description: >- Only the rendition fields that are specified here are returned for each result. Any rendition field is a valid value and these can be specified in a comma-separated list. For example, to list the rendition fields ID and resource, provide the value resource fields = ID, resource. All rendition fields are returned by default. required: false type: string - name: offset in: query description: >- Use the offset parameter to specify the number of renditions to skip from the beginning of the list and return the rest. required: false type: integer - name: limit in: query description: >- Set the limit for the maximum number of renditions to return in a single result. The default value is 50. required: false type: integer - name: order in: query description: >- Specify whether you want the renditions to be returned in ascending or descending order. Documents are returned in descending order by default. required: false type: string enum: - ascending - descending default: descending tags: - Authoring renditions responses: '200': description: >- Successfully lists a paged result view of all renditions that was created within the date range specified. schema: *ref_206 '400': description: >- The provided parameters are invalid. Please read the error message and alter the request accordingly. schema: *ref_1 '429': *ref_165 '503': *ref_207 default: *ref_208 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/image-profiles: post: summary: Create new image profiles. description: >- Use the /image-profiles end-point to create a new image profile.
User roles: admin, manager parameters: - name: body in: body description: Contains the image profile to create. required: true schema: *ref_209 responses: '200': description: Success. schema: *ref_40 '400': description: Empty body or Invalid input. schema: *ref_210 '404': description: Current tenant's database is not provisioned. schema: *ref_210 '409': description: Image profile with the same name exists. '429': *ref_165 '500': description: Unexpected error. schema: *ref_210 x-ibm-dx-security-user-roles: - admin - manager tags: - Authoring image profiles get: summary: Retrieve all image profiles in the database. description: >- Use the /image-profiles endpoint to retrieve all image profiles from the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of image profiles to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of image profiles that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the image profiles to be returned in ascending/alphabetical (default) or descending/reverse-alphabetical order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the image profile fields that are specified here are returned for each result. Any image profile field is a valid value and can be specified as a comma-separated list. type: string required: false - name: include in: query description: > Specifies additional fields to include with each result. Valid options are: * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both the fields that are specified in the 'fields' option and the fields in the 'include' option are returned. type: string required: false responses: '200': description: Success. schema: *ref_211 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring image profiles /authoring/v1/image-profiles/count: get: summary: Retrieve the total number of image profiles. description: >- Use the /image-profiles/count endpoint to obtain the total number of image profiles within the database.
User roles: admin, manager, editor, viewer responses: '200': description: image-profile count schema: *ref_212 '429': *ref_165 default: description: Unexpected error. schema: *ref_210 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring image profiles '/authoring/v1/image-profiles/{id}': put: summary: Update an existing image profile. description: >- Use the /image-profiles/{id} end-point to update an existing image profile within the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the image profile document to update. type: string required: true - name: forceOverride in: query description: Specifies whether revision checking should be disabled. type: boolean default: false required: false - name: body in: body description: Contains the updated image profile object to save. required: true schema: *ref_40 responses: '200': description: Success. schema: *ref_40 '400': description: Invalid ID or Invalid input. schema: *ref_210 '401': description: The user is not authorized to run this action. schema: *ref_210 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_210 '409': description: >- Another user updated the document since it was last retrieved OR when changing the document name, there is an existing document with the chosen name. schema: *ref_210 '429': *ref_165 '500': description: Unexpected error. schema: *ref_210 x-ibm-dx-security-user-roles: - admin - manager tags: - Authoring image profiles delete: summary: Delete an existing image profile. description: >- Use the /image-profiles/{id} endpoint to delete an existing image profile from the database.
User roles: admin, manager parameters: - name: id in: path description: The ID of the image profile to delete. type: string required: true responses: '200': description: Success. '400': description: Invalid ID OR Invalid input. schema: *ref_210 '401': description: The user is not authorized to run this action. schema: *ref_210 '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_210 '429': *ref_165 '500': description: Unexpected error. schema: *ref_210 x-ibm-dx-security-user-roles: - admin - manager tags: - Authoring image profiles get: summary: Retrieve an existing image profile. description: >- Use the /image-profiles/{id} end-point to retrieve an existing image profile from the database.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: The ID of the image profile to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any type document field is a valid value. type: string required: false - name: include in: query description: > A comma separated list of additional fields (which are normally hidden) to add to the response. Valid options are: * metadata: Adds additional details such as creator and last modifier to the response. * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both sets of fields are returned. ie. those specified in the 'fields' option and those specified in the 'include' option. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the image profile retrieved is the most recent version. If the image profile is the most recent version, the call returns a 304 ( Not modified) message instead of sending the image profile back. type: string required: false responses: '200': description: Success. schema: *ref_40 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '404': description: >- The document with ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_210 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring image profiles /authoring/v1/image-profiles/views/by-modified: get: summary: >- Retrieve all image profiles in the database ordered by last modified date. description: >- 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 parameters: - name: start in: query required: false type: string format: date-time description: > Provide the date and time of when the last modifications were made to the image profiles that you want returned. When the order is ascending (default), the image profiles that are modified on or after this date and time are returned. When the order is descending, the image profiles that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. - name: end in: query required: false type: string format: date-time description: > Provide the date and time of when the last modifications were made to the image profiles that you want returned. When the order is ascending (default), the image profiles that are modified on or before this date and time are returned. When the order is descending, the image profiles that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. - name: startId in: query required: false type: string description: > If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. - name: endId in: query required: false type: string description: > If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. - name: offset in: query description: >- Use the offset parameter to specify the number of image profiles to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of image profiles that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the image profiles to be returned in ascending/oldest-first (default) or descending/newest-first order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the image profile fields that are specified here are returned for each result. Any image profile field is a valid value and can be specified as a comma-separated list. type: string required: false - name: include in: query description: > Specifies additional fields to include with each result. Valid options are: * all: Adds all current and future additional fields to the response. When used in-conjunction with the 'fields' option, both the fields that are specified in the 'fields' option and the fields in the 'include' option are returned. type: string required: false responses: '200': description: Success. schema: *ref_211 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring image profiles /authoring/v1/resources: post: tags: - Authoring resources summary: Create a new resource. description: >- 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 consumes: - '*/*' produces: - application/json responses: '201': description: Successfully created a new resource and the ID is returned. schema: type: object properties: id: type: string required: - id example: id: 2322e04f11e47edbc6505ad8294ebd70 '400': description: >- The required parameters are missing or invalid, the binary size limit was exceeded, or the checksum provided was not correct. Please read the error message and alter the request accordingly. schema: *ref_2 '429': *ref_165 '503': *ref_213 default: *ref_214 parameters: - name: binary in: body description: Provide the binary data that is required to create a resource. required: true schema: type: string format: binary - name: Content-Type in: header type: string description: Provide the media type of the binary. required: true default: application/octet-stream - name: name in: query type: string description: Provide a name for the resource that you want to create. required: true - name: md5 in: query type: string description: Provide the Base64 encoded MD5 checksum of the resource. required: false x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/resources/{id}': get: tags: - Authoring resources summary: Retrieve an existing resource. description: >- 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 produces: - '*/*' parameters: - name: id in: path description: Provide the ID of the resource that you want to retrieve. required: true type: string - name: mode in: query description: >- Provide the option to set the response Content-Disposition as an attachment. required: false type: string enum: - download - name: bypass-cache in: query description: Force bypassing intermediate caches by providing a unique token. required: false type: string responses: '200': description: >- Successfully retrieved the binary of the resource that matches the ID you provided. schema: format: binary title: binary string headers: Content-Disposition: description: >- Suggests whether to attempt to open the file when processing or to save it. A file name is suggested to save the file. type: string '206': description: >- Successfully retrieved the request bytes of the resource that matches the ID you provided. schema: format: binary title: binary string headers: Content-Disposition: description: >- Suggests whether to attempt to open the file when processing or to save it. A file name is suggested to save the file. type: string '404': description: The resource with the provided ID was not found. schema: *ref_2 '429': *ref_165 '503': *ref_213 default: *ref_214 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: tags: - Authoring resources summary: Create a resource at the given id. description: >- 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 consumes: - '*/*' produces: - application/json responses: '200': description: The resource provided already exists at the given ID. '201': description: Successfully created a resource at the given ID. '400': description: >- The required parameters are missing or invalid, the binary size limit was exceeded, or the checksum provided was not correct. Please read the error message and alter the request accordingly. schema: *ref_2 '409': description: A resource with a different checksum exists at the given ID. schema: *ref_2 '429': *ref_165 '503': *ref_213 default: *ref_214 parameters: - name: binary in: body description: Provide the binary data that is required to create a resource. required: true schema: type: string format: binary - name: Content-Type in: header type: string description: Provide the media type of the binary. required: true default: application/octet-stream - name: name in: query type: string description: Provide a name for the resource that you want to create. required: true - name: id in: path description: Provide the ID of the resource that you want to create. required: true type: string - name: md5 in: query type: string description: Provide the Base64 encoded MD5 checksum of the resource. required: true x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/resources/views/by-created: get: summary: Retrieve all resources created within the specified date range. description: >- Use this endpoint to retrieve all resources that was created within the date range specified.
User roles: admin, manager, editor, viewer parameters: - name: start in: query required: false type: string format: date-time description: >- Provide the date and time of when the resource was created. Resources that were created on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: end in: query required: false type: string format: date-time description: >- Provide the date and time of when the resource was created. Resources that were created on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. Note: when reversing the order you do not switch start and end. - name: startId in: query required: false type: string description: >- If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. Note: when reversing the order you do not switch start and end ids. - name: endId in: query required: false type: string description: >- If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. Note: when reversing the order you do not switch start and end ids. - name: limit in: query required: false type: number format: integer description: >- Set the limit for the maximum number of resource items to return in a single result. The default value is 50. You can pass 0 to unset the limit and stream all available results. A streaming parser can be avoided with format=sequence. - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: offset in: query required: false type: number format: integer description: >- Use the offset parameter to specify the number of resource items to skip from the beginning of the list and return the rest. Note: large offsets perform poorly. Use start keys to index into large result sets. Also see pageMode. - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query required: false type: string enum: - ascending - descending description: > Specify the order of the results. * `ascending` - (default) result keys are increasing * `descending` - result keys are decreasing It is not necessary to switch the start and end keys and ids when reversing the order. tags: - Authoring resources responses: '200': description: >- Successfully lists a paged result view of all resources that was created within the date range specified. schema: *ref_215 '400': description: >- The provided parameters are invalid. Please read the error message and alter the request accordingly. schema: *ref_2 '429': *ref_165 '503': *ref_213 default: *ref_214 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/review: post: summary: Start a review. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: body in: body description: >- Provide the review item fields such as name, targetDate, and items. The name field is required. required: true schema: *ref_216 tags: - Authoring review responses: '201': description: Successfully created a review. headers: x-ibm-dx-failures: description: >- This header contains the IDs of the failed items when creating a review. type: array items: type: string schema: *ref_217 '400': description: >- The body parameter is empty or has an invalid input. Provide valid input values to create a review. schema: *ref_218 '429': *ref_165 '503': description: >- Unable to create the review as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/review/{id}': get: summary: Retrieve an existing review. description: >- 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 produces: - application/json parameters: - name: id in: path description: Provide the ID of the review that you want to retrieve. type: string required: true tags: - Authoring review responses: '200': description: >- Successfully retrieved the API representation for the existing review that matches the ID that you provided. schema: *ref_217 '404': description: 'The review with ID {id} was not found.' schema: *ref_218 '429': *ref_165 '503': description: >- Unable to retrieve the review from the database as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer put: summary: Update an existing review. description: >- Use the /review/{id} end point to update an existing review that matches the ID that is specified.
User roles: admin, manager, editor parameters: - name: id in: path description: Provide the ID of the review that you want to update. type: string required: true - name: body in: body description: >- Provide the review item fields such as name, targetDate, and items. The current revision must be provided in order to update the review. required: false schema: *ref_219 tags: - Authoring review responses: '200': description: >- Successfully updated the review that matches the ID that you provided. schema: *ref_217 '400': description: >- The update request is invalid or the request failed validation. Provide valid values and try again. schema: *ref_218 '404': description: 'The review with ID {id} was not found.' schema: *ref_218 '409': description: >- Unable to update the review with the ID "{0}" because another user updated the review since it was last retrieved. Retrieve the review again and reapply your changes. schema: *ref_218 '429': *ref_165 '503': description: >- Unable to retrieve the review from the database as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor delete: summary: Delete an existing review. description: >- Use the /review/{id} endpoint to delete an existing review in the database.
User roles: admin, manager, editor parameters: - name: id in: path description: Provide the ID of the review that you want to delete. type: string required: true tags: - Authoring review responses: '200': description: >- Successfully deleted the review that matches the ID that you provided. '404': description: 'The review with ID {id} was not found.' schema: *ref_218 '409': description: >- Unable to delete the review with the ID "{0}" because another user updated the review since it was last retrieved. schema: *ref_218 '429': *ref_165 '503': description: >- Unable to delete the review in the database as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/review/{id}/approve': post: summary: Approve items in a review. description: >- 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 consumes: - application/json parameters: - name: id in: path description: Provide the ID of the review that you want to approve. type: string required: true - name: body in: body description: Provide the unique IDs of the items that you want to approve. required: true schema: *ref_220 tags: - Authoring review responses: '200': description: Successfully approved the items in the specified review. headers: x-ibm-dx-failures: description: >- This header contains the IDs of the failed items when approving items in a review. type: array items: type: string '400': description: >- The required parameters are missing or invalid. Provide valid parameters and try again. schema: *ref_218 '429': *ref_165 '503': description: >- Unable to approve the items in the review as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/review/{id}/approve-all': post: summary: Approve all items in a review. description: >- 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 consumes: - application/json parameters: - name: id in: path description: Provide the ID of the review that you want to approve. type: string required: true tags: - Authoring review responses: '200': description: Successfully approved all the items in the specified review. headers: x-ibm-dx-failures: description: >- This header contains the IDs of the failed items when approving all items in a review. type: array items: type: string '400': description: >- The required parameters are missing or invalid. Provide valid parameters and try again. schema: *ref_218 '429': *ref_165 '503': description: >- Unable to approve all the items in the review as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor '/authoring/v1/review/{id}/complete': post: summary: Complete a review. description: >- 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 produces: - application/json parameters: - name: id in: path description: Provide the ID of the review that you want to end. type: string required: true tags: - Authoring review responses: '200': description: >- Successfully completed the review that matches the ID that you provided. headers: x-ibm-dx-failures: description: >- This header contains the IDs of the failed items when completing a review. type: array items: type: string '404': description: 'The review with ID {id} was not found.' schema: *ref_218 '429': *ref_165 '503': description: >- Unable to end the specified review as the service is unavailable. Try again later. schema: *ref_218 default: description: Unexpected error. schema: *ref_218 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/search: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring search summary: Search in the authoring collection description: >- 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 produces: - application/json parameters: - name: defType description: >- The Solr "defType" parameter. Specify "defType=edismax" to use the edismax query parser. in: query required: false type: string - name: df description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: facet description: >- The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters. in: query required: false type: string - name: facet.contains description: >- The Solr "facet.contains" parameter returns only facets containing this term. in: query required: false type: string - name: facet.containsIgnoreCase description: >- The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied. in: query required: false type: string - name: facet.field description: >- The Solr "facet.field" parameter identifies a field to be used as a facet. in: query required: false type: string - name: facet.limit description: >- The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100. in: query required: false type: string - name: facet.offset description: >- The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0. in: query required: false type: string - name: facet.prefix description: >- The Solr "facet.prefix" parameter returns only facets with this prefix. in: query required: false type: string - name: facet.range description: The Solr "facet.range" parameter. in: query required: false type: string - name: facet.range.end description: The Solr "facet.range.end" parameter. in: query required: false type: string - name: facet.range.gap description: The Solr "facet.range.gap" parameter. in: query required: false type: string - name: facet.range.start description: The Solr "facet.range.start" parameter. in: query required: false type: string - name: fl description: >- The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields that are highlighted in the "Stored" column of the table at the beginning of this document. in: query required: false type: string - name: fq description: >- The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string - name: f.. description: >- Many "facet" parameters can be overridden on a per-field basis using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of 5 terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5". in: query required: false type: string - name: indent description: >- If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts at indenting the XML response such that it is easier to read. The default behavior is not to indent the XML response. in: query required: false type: string - name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: false type: string - name: qf description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: rows description: >- The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000. in: query required: false type: integer - name: sort description: >- The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. in: query required: false type: string - name: start description: >- The Solr "start" parameter specifies an offset into the responses, which are returned and can be used for paging query results. Default value is 0. in: query required: false type: integer responses: '200': description: >- See the description above for examples of response data for different queries. '400': schema: *ref_221 description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. '404': schema: *ref_221 description: Not found - The authoring collection was not found. '414': schema: *ref_221 description: >- The request URL that addresses the search service is larger than the supported size of 4,096 bytes. Reduce the length of the query. '429': *ref_165 '500': schema: *ref_221 description: >- Internal server error - Unable to complete your request due to an exception. Try again later. /authoring/v1/search/json: parameters: [] post: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer tags: - Authoring search summary: Search in the authoring collection using post request with json body description: |- The request body contains an json object with search query
User roles: admin, manager, editor, viewer consumes: - application/json produces: - application/json responses: '200': description: >- See the description above for examples of response data for different queries. '400': schema: *ref_221 description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. '404': schema: *ref_221 description: Not found - The authoring collection was not found. '414': schema: *ref_221 description: >- The request URL that addresses the search service is larger than the supported size of 4,096 bytes. Reduce the length of the query. '429': *ref_165 '500': schema: *ref_221 description: >- Internal server error - Unable to complete your request due to an exception. Try again later. /authoring/v1/sites: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Get list of all sites description: >- Returns a list of all sites. A default site with id 'default' exists out of the box.
User roles: admin, manager, editor, viewer produces: - application/json parameters: - name: fields in: query description: > Reduce the returned site metadata down to just the specified fields. Fields specified by a comma seperated list of field names and should only be used once in query string. To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`. required: false type: string items: type: string collectionFormat: csv responses: '200': description: Success schema: *ref_222 examples: application/json: items: - name: default classification: site routingMode: anchor lastModified: '2017-09-11T14:03:04.348Z' lastModifierId: 00000000-0000-0000-0000-000000000009 created: '2017-09-11T14:03:04.348Z' creatorId: 00000000-0000-0000-0000-000000000009 id: default rev: 1-76a0d8566675d83395d8878fab7d4e5e '429': *ref_165 default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Create a new site description: >- 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 produces: - application/json consumes: - application/json parameters: - name: site in: body description: The metadata for the new site required: true schema: *ref_224 - name: copySourceSiteId in: query description: > If ‘copySourceSiteId’ is specified when creating a site then a new site is created and all the pages from the source site are copied into the new site. type: string required: false responses: '201': description: succcess. schema: *ref_53 examples: application/json: name: default routingMode: anchor storeId: '' storeIdentifier: '' linkedDocId: default classification: site lastModified: '2018-07-17T15:17:02.203Z' lastModifierId: d30a541e-ff2e-45a8-a0eb-52952a3cd6eb creatorId: 00000000-0000-0000-0000-000000000009 created: '2018-07-16T15:56:20.009Z' status: ready id: 'default:fc81b9d3-76a7-4bd1-8ddc-a23cc9e4b101' rev: 68-8f553a9520a1f3be3b21fd6cc8684dd5 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - errorKey: SITE_ITEM_INVALID_ERROR code: 2003 statusCode: '400' message: >- Site metadata supplied is invalid, the 'linkedDocId' may be missing or empty. messageParameters: field: linkedDocId '409': description: Conflict schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '69982173950058' errors: - code: 2096 message: >- Unable to create site with ID: default:fc81b9d3-76a7-4bd1-8ddc-a23cc9e4b101 due to a conflict. level: ERROR description: >- Unable to create the specified site due to a conflict with an existing item. You may have attempted to create the site but the site already exists. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Retrieve metadata for a site. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: fields in: query description: > Optional. Only the site metadata fields that are specified here are returned for each result. Any site metadata field is a valid value and can be specified as a comma-separated list. Field names should only be specified once in the list. For example, to only retrieve `name` and `rev` this parameter should look like `fields=name,rev`. required: false type: string items: type: string collectionFormat: csv responses: '200': description: Success schema: *ref_53 examples: application/json: name: default classification: site routingMode: anchor lastModified: '2017-09-11T14:03:04.348Z' lastModifierId: 00000000-0000-0000-0000-000000000009 created: '2017-09-11T14:03:04.348Z' creatorId: 00000000-0000-0000-0000-000000000009 id: default rev: 1-76a0d8566675d83395d8878fab7d4e5e '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites put: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Update metadata for a site. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: body in: body description: >- Provide the updated site metadata in the body of the request. The current revision (`rev`) and the site name (`name`) fields must be provided in order to update the site metadata. required: true schema: *ref_225 - name: Content-Type in: header description: 'Content type of the request body, should be ''application/json''' type: string required: true - name: forceOverride in: query description: > Force update of the existing site metadata without requiring the current `rev` value. When set to `true` this request will overwrite the stored site metadata regardless of a difference in revisions. type: boolean required: false responses: '200': description: 'Success, returns updated site' schema: *ref_226 examples: application/json: name: default id: default rev: 22-ae719cf45c00a55eda54d6480976b3e1 classification: site '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2003 message: Site metadata supplied is invalid level: ERROR description: >- The site metadata supplied is invalid. Provide a valid site metadata value and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '409': description: Conflict schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2051 message: 'Unable to update site with ID: default due to a conflict.' level: ERROR description: >- Unable to update the specified site due to a conflict with an existing item. You may have attempted to update the site with an older version. Resolve the conflict and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites delete: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Delete a site and the site pages description: |- Use this endpoint to delete a site and the pages in that site.
User roles: admin, manager, editor produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid responses: '204': description: Site successfully deleted. '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '409': description: conflict schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 6016 message: Some of the pages for site dummyId could not be deleted. level: ERROR description: >- A site with the specified ID could not be deleted as some of the pages in the site could not be deleted. Please try again. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/ready': post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Promote the site and pages metadata from draft to ready status. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the draft site. required: true type: string format: uuid responses: '200': description: Successfully changed the status of the site from draft to ready. schema: *ref_53 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455571' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/cancel': post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Cancel the draft site metadata undoing any modifications. description: |- Use this endpoint to undo changes to the site's metadata.
User roles: admin, manager, editor produces: - application/json parameters: - name: site-id in: path description: The ID of the draft site. required: true type: string format: uuid responses: '200': description: Successfully cancelled the draft site metadata. '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455571' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages/ready': post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: >- Bulk promote the specified page Ids in the specified site from draft to ready status. description: >- Use this endpoint to change the status of multiple pages in a specific site from draft to ready.
User roles: admin, manager, editor produces: - application/json parameters: - name: site-id in: path description: The ID of the draft site. required: true type: string format: uuid - name: ids in: body description: The array of draft page Ids to ready required: true schema: *ref_227 responses: '204': description: >- Successfully changed the status of all specified pages in the site from draft to ready. '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455571' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: | Get the full page hierarchy for a site. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned page metadata down to just the specified fields in the returned page hierarchy. Fields specified by a comma seperated list of field names and should only be used once in query string. To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`. required: false type: string items: type: string collectionFormat: csv - name: include in: query description: > Specify additional fields to include with each result. The following fields can be specified to be included in the page item: 'hierarchicalPath', 'route'. You can specify multiple fields as a comma-separated value. For example, include=hierarchicalPath,route. The hierarchicalPath field is a concatenation of each ancestor page name field and the route field is a concatenation of each ancestor page segment field. type: string required: false - name: responseFormat in: query description: >- Specify the format for the response. Valid values are 'hierarchical' and 'list'. Default is 'hierarchical'. required: false type: string default: hierarchical responses: '200': description: succcess. schema: *ref_228 examples: application/json: items: - id: 1067771c-ec05-4671-951b-18f503953f2d rev: 22-ae719cf45c00a55eda54d6480976b3e1 name: home segment: home contentTypeId: ab7288e3-42r3-h34s-72nm-34vfk4gf894g description: home page layoutId: 7655c56d-39ee-4c4d-8689-00bd1c08e6ff title: Home Page contentId: 68eb88a6-31d8-4e47-ad5f-da932081b68d route: /home position: 0 classification: page hideFromNavigation: false children: - id: aw67771c-ec05-4671-951b-18fqwq53f2d rev: 20-axz19cf45c00a55eda54d6480976b3e1 name: products segment: products contentTypeId: dffa969c-32fc-4079-8a57-eb85ad136ae8 description: products page layoutId: 13c46fbe-db14-4a24-859f-f4b847a2b843 title: Products Page contentId: 76sd88a6-31d8-4e47-ad5f-da932081b68d route: /home/products parentId: 1067771c-ec05-4671-951b-18f503953f2d position: 0 hideFromNavigation: false children: [] - id: 1067771c-ec05-4671-951b-18f632153f2d rev: 22-ae719cf45c00a55eda54d6480ab6b3e1 name: search results segment: search-results contentTypeId: ab7288e3-4ar3-h34s-72nm-3fvf3agf894g description: search results page layoutId: 7655c56d-39ee-4c4d-8689-00be1c0854ff title: Search Results contentId: 68b192a6-31d8-4e47-ad5f-da472081b68d route: /search-results position: 0 classification: page hideFromNavigation: true children: [] '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites post: x-ibm-dx-security-user-roles: - admin - manager summary: Create a page. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: page in: body description: The metadata for the new page. required: true schema: *ref_229 - name: cloneContentId in: query description: > Clone the provided content item and to use the clone for this new page. If 'contentId' is set on the body, it is ignored and replaced with the id of the newly cloned content Item A non zero length value for 'contentTypeId' in the body must be specified to satisify the API requirements. type: string required: false - name: copySourcePageId in: query description: > If ‘copySourcePageId’ is specified when creating a page then a new page is created by making a deep copy of the source page and its content. type: string required: false responses: '201': description: succcess. schema: *ref_55 examples: application/json: id: aw67771c-ec05-4671-951b-18fqwq53f2d rev: 1-axz19cf45c30a58eda54d6480974b3e1 name: products segment: products contentTypeId: dffa969c-32fc-4079-8a57-eb85ad136ae8 description: products page layoutId: 13c46fbe-db14-4a24-859f-f4b847a2b843 title: Products Page contentId: 76sd88a6-31d8-4e47-ad5f-da932081b68d parentId: 1067771c-ec05-4671-951b-18f503953f2d position: 0 hideFromNavigation: false classification: page lastModified: '2017-09-11T14:03:04.348Z' lastModifierId: 00000000-0000-0000-0000-000000000009 created: '2017-09-11T14:03:04.348Z' creatorId: 00000000-0000-0000-0000-000000000009 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages/views/by-modified': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Get pages modified between two dates. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: start in: query description: >- Provide the date and time of when the last modifications were made to the page items that you want returned. The page items that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. type: string format: date-time required: false - name: end in: query description: >- Provide the date and time of when the last modifications were made to the page items that you want returned. The page items that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. type: string required: false format: date-time - name: fields in: query description: >- Reduce the returned page metadata down to just the specified fields in the returned page hierarchy. Fields specified by a comma seperated list of field names and should only be used once in query string. To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`. type: string required: false items: type: string collectionFormat: csv - name: order in: query description: > Specify whether you want the page items to be returned in ascending or descending order. Documents are returned in ascending order by default. Supported order values are 'asc', 'ascending', 'desc' and 'descending' e.g. /sites/dummySitesId/pages/views/by-modified?order=descending returns the pages in descending order. type: string required: false - name: limit in: query description: >- Set the limit for the maximum number of items to return in a single result. The default value is 50. Use 0 for unlimited. If offset and limit are not set, all results are returned. type: number format: integer required: false - name: offset in: query description: >- Use the offset parameter to specify the number of items to skip from the beginning of the list and return the rest. The default value is 0. If offset and limit are not set, all results are returned. type: number format: integer required: false - name: include in: query description: > Specify additional fields to include with each result. The following fields can be specified to be included in the page item: 'hierarchicalPath', 'route'. You can specify multiple fields as a comma-separated value. For example, include=hierarchicalPath,route. The hierarchicalPath field is a concatenation of each ancestor page name field and the route field is a concatenation of each ancestor page segment field. type: string required: false responses: '200': description: succcess. schema: *ref_230 examples: application/json: items: - id: 1067771c-ec05-4671-951b-18f503953f2d rev: 22-ae719cf45c00a55eda54d6480976b3e1 name: home segment: home contentTypeId: ab7288e3-42r3-h34s-72nm-34vfk4gf894g description: home page layoutId: 7655c56d-39ee-4c4d-8689-00bd1c08e6ff title: Home Page contentId: 68eb88a6-31d8-4e47-ad5f-da932081b68d position: 0 hideFromNavigation: false classification: page - id: 2867771c-ec05-4671-951b-18f500053f2d rev: 20-ae719cf45c00a55eda54d6350976b3e1 name: About Us segment: about-us contentTypeId: ab7288e3-42r3-h34s-72nm-34vfk4gf894g description: About Us page layoutId: 7655c56d-39ee-4c4d-8689-00bd1c08e6ff title: About Us contentId: 68eb88a6-31d8-441e-ad5f-da932081b68d position: 1 hideFromNavigation: false classification: page - id: 35575721-ec45-9871-921b-18f500053f4d rev: 20-ae7a9cff5c00a55eda5dd6350976b3a1 name: Our Events segment: our-events contentTypeId: ab2748e3-42r3-h34s-72nm-34vfk4gf457g description: Events page layoutId: 7655c56d-39ee-4c4d-8689-00bd1c08e6ff title: Our Events page contentId: 62ab38a6-34a8-121e-dc32-de441563f6ad position: 0 parentId: 1067771c-ec05-4671-951b-18f503953f2d hideFromNavigation: false classification: page '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2005 message: Invalid site ID parameter provided. level: ERROR description: >- The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2002 message: 'Site not found for ID: dummyId' level: ERROR description: >- A site with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages/{page-id}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Get a page by id. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: page-id in: path description: ID of page. required: true type: string format: uuid - name: fields in: query description: > Reduce the returned page metadata down to just the specified fields. Fields specified by a comma seperated list of field names and should only be used once in query string. To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`. required: false type: string items: type: string collectionFormat: csv - name: include in: query description: > Specify additional fields to include with each result. The following fields can be specified to be included in the page item: 'hierarchicalPath', 'route'. You can specify multiple fields as a comma-separated value. For example, include=hierarchicalPath,route. The hierarchicalPath field is a concatenation of each ancestor page name field and the route field is a concatenation of each ancestor page segment field. type: string required: false responses: '200': description: succcess. schema: *ref_55 examples: application/json: id: aw67771c-ec05-4671-951b-18fqwq53f2d rev: 20-axz19cf45c00a55eda54d6480976b3e1 name: products segment: products contentTypeId: dffa969c-32fc-4079-8a57-eb85ad136ae8 description: products page layoutId: 13c46fbe-db14-4a24-859f-f4b847a2b843 title: Products Page contentId: 76sd88a6-31d8-4e47-ad5f-da932081b68d parentId: 1067771c-ec05-4671-951b-18f503953f2d position: 0 hideFromNavigation: false '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2011 message: Invalid page ID parameter provided. level: ERROR description: >- The page ID provided is missing or invalid. The page ID cannot be empty or contain spaces. Provide a valid page ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites delete: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Delete a page. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: page-id in: path description: ID of page. required: true type: string format: uuid - name: delete-content in: query description: >- Set to true to delete associated content. If delete-content is not specified the default is to not delete the associated content. required: false type: boolean responses: '204': description: Page successfully deleted. '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2011 message: Invalid page ID parameter provided. level: ERROR description: >- The page ID provided is missing or invalid. The page ID cannot be empty or contain spaces. Provide a valid page ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '409': description: Conflict schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 6001 message: >- There was a conflict deleting page: dummyId and its child pages. level: ERROR description: >- Unable to delete the page: {pageId} and its child pages due to conflict. Resolve the conflict and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites put: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Update a page. description: >- 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 consumes: - application/json produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: page-id in: path description: ID of page. required: true type: string format: uuid - name: page in: body description: The metadata for the updated page. required: true schema: *ref_231 - name: forceOverride in: query description: > Force update of the existing page metadata without requiring the current rev value. When set to `true` this request will overwrite the stored page metadata regardless of a difference in revisions. type: boolean required: false responses: '200': description: Page successfully updated. schema: *ref_55 examples: application/json: id: aw67771c-ec05-4671-951b-18fqwq53f2d rev: 20-axz19cf45c00a55eda54d6480976b3e1 name: products segment: products contentTypeId: dffa969c-32fc-4079-8a57-eb85ad136ae8 description: products page layoutId: 13c46fbe-db14-4a24-859f-f4b847a2b843 title: Products Page contentId: 76sd88a6-31d8-4e47-ad5f-da932081b68d parentId: 1067771c-ec05-4671-951b-18f503953f2d hideFromNavigation: false position: 0 classification: page lastModified: '2017-09-11T14:03:04.348Z' lastModifierId: 00000000-0000-0000-0000-000000000009 created: '2017-09-11T14:03:04.348Z' creatorId: 00000000-0000-0000-0000-000000000009 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2011 message: Invalid page ID parameter provided. level: ERROR description: >- The page ID provided is missing or invalid. The page ID cannot be empty or contain spaces. Provide a valid page ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: 1067771c-ec05-4671-951b-18f503953f2d' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '409': description: Conflict schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2025 message: >- The page with ID: 1067771c-ec05-4671-951b-18f503953f2d has a different 'rev' value than the one supplied. level: ERROR description: >- Unable to update the page. A page with the specified ID has a different 'rev' value than the one supplied. Change the 'rev' to be currently stored value and try to update the page again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages/move': post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Move a page. description: >- 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 produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: sourceId in: query description: The ID of the source page to move. required: true type: string format: uuid - name: sourceRev in: query description: the 'rev' value for the page to be moved. required: true type: string - name: targetId in: query description: The ID of the target page. required: false type: string format: uuid - name: targetRev in: query description: the 'rev' value for the target page. required: false type: string - name: targetPosition in: query description: The new position on the target page for the move. required: true type: integer responses: '200': description: succcess. schema: *ref_232 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2041 message: >- A target position of 10 is not valid for the children of page with ID dummyPage, so no move occurred level: ERROR description: >- Unable to move the page. The target position supplied is invalid for the target page. Change the targetPosition and try again locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/{site-id}/pages/{page-id}/ready': post: x-ibm-dx-security-user-roles: - admin - manager - editor summary: Promote the page from draft to ready status. description: |- Use this endpoint to change the status of a page from draft to ready.
User roles: admin, manager, editor produces: - application/json parameters: - name: site-id in: path description: The ID of the site. required: true type: string format: uuid - name: page-id in: path description: The ID of the draft page. required: true type: string format: uuid responses: '200': description: Successfully changed the status of the page from draft to ready. schema: *ref_55 '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455571' errors: - code: 2062 message: >- Unable to ready the draft of the page with ID: dummyDraftPageId in site with ID: dummySiteId as the page is not in a draft state. level: ERROR description: >- Unable to ready a draft of the page as the page is not in a draft state. Ensure the correct id is been used and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites '/authoring/v1/sites/pages/{page-id}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Get a page by unique id. description: >- 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 produces: - application/json parameters: - name: page-id in: path description: ID of page. required: true type: string format: uuid - name: fields in: query description: > Reduce the returned page metadata down to just the specified fields. Fields specified by a comma seperated list of field names and should only be used once in query string. To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`. required: false type: string items: type: string collectionFormat: csv - name: include in: query description: > Specify additional fields to include with each result. The following fields can be specified to be included in the page item: 'hierarchicalPath', 'route'. You can specify multiple fields as a comma-separated value. For example, include=hierarchicalPath,route. The hierarchicalPath field is a concatenation of each ancestor page name field and the route field is a concatenation of each ancestor page segment field. type: string required: false responses: '200': description: succcess. schema: *ref_55 examples: application/json: id: aw67771c-ec05-4671-951b-18fqwq53f2d rev: 20-axz19cf45c00a55eda54d6480976b3e1 name: products segment: products contentTypeId: dffa969c-32fc-4079-8a57-eb85ad136ae8 description: products page layoutId: 13c46fbe-db14-4a24-859f-f4b847a2b843 title: Products Page contentId: 76sd88a6-31d8-4e47-ad5f-da932081b68d parentId: 1067771c-ec05-4671-951b-18f503953f2d position: 0 hideFromNavigation: false '400': description: Bad request schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2011 message: Invalid page ID parameter provided. level: ERROR description: >- The page ID provided is missing or invalid. The page ID cannot be empty or contain spaces. Provide a valid page ID and try again. locale: en '401': description: Unauthorized schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '403': description: Forbidden schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1016 message: Problem accessing database. level: ERROR description: >- Problem accessing database. Try again or contact Acoustic support if problem persists. locale: en '404': description: Not found schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 2012 message: 'Page not found for ID: dummyId' level: ERROR description: >- A page with the specified ID was not found in the system. Provide a valid ID and try again. locale: en '429': description: Too Many Requests schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 1018 message: Temporarily unable to access the database. level: ERROR description: >- Temporarily unable to access the database. Try again or contact Acoustic support if problem persists. locale: en default: description: Unexpected error schema: *ref_223 examples: application/json: service: prod-authoring-sites requestId: '455478465455511' errors: - code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Authoring sites /authoring/v1/types: post: tags: - Authoring types summary: Create new type documents. description: >- 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 parameters: - name: body in: body description: >- Provide all the type fields that are needed to create the new content type. required: true schema: *ref_233 responses: '200': description: >- Successfully created a new content type with all the requested fields. schema: *ref_67 '400': description: >- The body parameter is empty or has an invalid input. Provide valid type fields that are required to create the new content type. schema: *ref_234 '404': description: Current tenant's database is not provisioned. schema: *ref_234 '409': description: >- A content type document with the same name or path exists in the database. Provide a new name or path for this content type. '429': *ref_165 '500': description: Unexpected error. schema: *ref_234 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring types summary: Retrieve all type documents in the database. description: >- Use the /types endpoint to retrieve all content type documents from the database.
User roles: admin, manager, editor, viewer parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of type documents to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of type documents that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the type documents to be returned in ascending/alphabetical (default) or descending/reverse-alphabetical order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the content type fields that are specified here are returned for each result. Any type document field is a valid value and can be specified as a comma-separated list. type: string required: false - *ref_235 responses: '200': description: Successfully lists all content type documents that are requested. schema: *ref_236 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/types/by-path: get: tags: - Authoring types summary: Retrieve an existing type by its path. description: >- Use the /types/by-path end-point to retrieve an existing content type from the database.
User roles: admin, manager, editor, viewer parameters: - name: path in: query description: The path of the content type to retrieve. type: string required: true - name: fields in: query description: >- A comma separated list that when specified, limits the fields returned to just those specified. Any type document field is a valid value. type: string required: false - *ref_237 - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the content type document retrieved is the most recent version. If the content type document is the most recent version, the call returns a 304 (Not modified) message instead of sending the content type document back. type: string required: false responses: '200': description: Success. schema: *ref_67 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '400': description: Invalid path OR Invalid input. schema: *ref_234 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_234 '404': description: >- The document with path {path} was not found OR Current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/types/count: get: tags: - Authoring types summary: Retrieve the total number of types. description: >- Use the /types/count endpoint to obtain the total number of content types within the database.
User roles: admin, manager, editor, viewer responses: '200': description: types count schema: *ref_238 '429': *ref_165 default: description: Unexpected error. schema: *ref_234 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/types/{id}': put: tags: - Authoring types summary: Update an existing type. description: >- Use the /types/{id} end-point to update an existing content type within the database.
User roles: admin, manager parameters: - name: id in: path description: Provide the ID of the content type document that you want to update. type: string required: true - name: forceOverride in: query description: Specifies whether revision checking should be disabled. type: boolean default: false required: false - *ref_239 - name: body in: body description: >- Provide all the updated type fields that you want to save to this content type document. required: true schema: *ref_67 responses: '200': description: >- Successfully updated the content type document that matches the ID provided with the changes made to the type fields. schema: *ref_67 '400': description: The ID that you provided is invalid. Provide a valid ID. schema: *ref_234 '401': description: You do not have authorization to update this content type document. schema: *ref_234 '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '409': description: >- The content type document was updated by another user since you retrieved it. If you are changing the document path, a content type document with the same path exists in the database. Provide a new path for this content type. schema: *ref_234 '429': *ref_165 '500': description: Unexpected error. schema: *ref_234 x-ibm-dx-security-user-roles: - admin - manager delete: tags: - Authoring types summary: Delete an existing type. description: >- Use the /types/{id} endpoint to delete an existing content type from the database.
User roles: admin, manager parameters: - name: id in: path description: Provide the ID of the content type document that you want to delete. type: string required: true - name: cascade in: query description: > Lists the associated artifacts that should be deleted at the same time. Valid options are: * mappings: Deletes the associated layout-mapping. type: string required: false responses: '200': description: >- Successfully deleted the content type document that matches the ID that you provided. '400': description: >- The ID provided is invalid, provide a valid ID. Or a draft item that is created from the content type document exists. Therefore, the content type document cannot be deleted. schema: *ref_234 '401': description: You do not have authorization to delete this content type document. schema: *ref_234 '404': description: >- A content type document with the ID {id} was not found OR Current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 '500': description: Unexpected error. schema: *ref_234 x-ibm-dx-security-user-roles: - admin - manager get: tags: - Authoring types summary: Retrieve an existing type. description: >- Use the /types/{id} end-point to retrieve an existing content type from the database.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: >- Provide the ID of the content type document that you want to retrieve. type: string required: true - name: fields in: query description: >- Only the content type fields that are specified here are returned for each result. Any type document field is a valid value and can be specified as a comma-separated list. type: string required: false - *ref_237 - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the content type document retrieved is the most recent version. If the content type document is the most recent version, the call returns a 304 ( Not modified) message instead of sending the content type document back. type: string required: false responses: '200': description: >- Successfully retrieved the existing content type document that matches the ID that you provided. schema: *ref_67 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified. The Etag value that you provided in the If-Match parameter matches the recent document version. '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/types/{id}/copy': post: tags: - Authoring types summary: Copies an existing type. description: >- 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 parameters: - name: id in: path description: Provide the ID of the content type document that you wish to copy. type: string required: true - name: name in: query description: >- An optional name to associate with the copy. If there is an existing content-type with the specified name, then the copied document will have a name in the format 'Copy [NUMBER] of [NAME]' type: string required: false - name: cascade in: query description: > Lists the associated artifacts that should be copied at the same time. Valid options are: * mappings: Also copies layout-mapping associated with the original content type. * defaults: Also copies default-content associated with the original content type. * all : Copies mappings as well as defaults. type: string required: false responses: '201': description: Successfully copied the content type document. schema: *ref_67 '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager '/authoring/v1/types/{id}/new-content': get: tags: - Authoring types summary: Returns a skeleton content item based on the specified content-type. description: >- 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 parameters: - name: id in: path description: >- Provide the ID of the content type document that you wish to generate the content against. type: string required: true - name: include in: query description: > Specify additional information to include on the content item. Valid options are: * values: Adds empty value attributes to each content element. Note that some empty values, such as `id=""`, may not pass content validation. * defaults: Attempts to add default values to each content element. If this is set but `defaultContentId` is not specified, elements may be populated from a default-content item matching the specified type. If both defaults and values are requested (e.g. `include=all` or `include=values,defaults`), empty value attributes will be added for elements that were not found on the default content. * all: Adds all current and future additional information to the response. required: false type: string - name: defaultContentId in: query description: > Specify a default content item to populate the generated content. If provided, and the item exists, elements and other fields will be copied across to the returned content item. required: false type: string - name: valuesForGroup in: query description: > if element is group - returns in the response payload value/values and typeRef if element is NOT group - returns value/values only if defaults elements are defined type: boolean default: false required: false responses: '200': description: Successfully created the skeleton content item. schema: *ref_240 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified. The Etag value that you provided in the If-Match parameter matches the recent content version. '400': description: >- A default content document with the ID {defaultContentId} was not found, or it did not have a content type matching {id}. '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/types/{id}/schema': get: tags: - Authoring types summary: Retrieve the Json-Schema representation of the document. description: >- 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 parameters: - name: id in: path description: >- Provide the ID of the content type document for which you need to get the Json-Schema. type: string required: true - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the content type document retrieved is the most recent version. If the content type document is the most recent version, the call returns a 304 (Not modified) message instead of sending the schema back. type: string required: false responses: '200': description: Successfully retrieved the Json-Schema of the content type document. headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified. The Etag value that you provided in the If-Match parameter matches the recent document version. '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/types/{id}/validate': post: tags: - Authoring types summary: >- Validate the supplied type document instance (eg. content item) against the specified type. description: >- 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 parameters: - name: id in: path description: >- Provide the ID of the content type document that you want to validate against. type: string required: true - name: body in: body description: Provide all the type document instances to validate. required: true schema: {} responses: '200': description: Validation of the content item against specidfied type passed. schema: *ref_241 '400': description: >- The ID that you provided is invalid, or validation of the content against specified type failed. Provide a valid ID and valid content. schema: *ref_241 '401': description: >- You do not have authorization to validate this content type document. schema: *ref_234 '404': description: >- A content type document with the ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/types/new: get: tags: - Authoring types summary: Retrieve a blank content type. description: >- Use the /types/new end-point to get a blank content type document.
User roles: admin, manager, editor, viewer parameters: - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the content type document retrieved is the most recent version. If the content type document is the most recent version, the call returns a 304 ( Not modified) message instead of sending the blank content type document back. type: string required: false responses: '200': description: Successfully retrieved a blank content type document. schema: *ref_233 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified. The Etag value that you provided in the If-Match parameter matches the recent document version. '404': description: >- Existing initial blank content type document was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/types/views/by-modified: get: tags: - Authoring types summary: >- Retrieve all type documents in the database ordered by last modified date. description: >- 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 parameters: - name: start in: query required: false type: string format: date-time description: > Provide the date and time of when the last modifications were made to the content types that you want returned. When the order is ascending (default), the content types that are modified on or after this date and time are returned. When the order is descending, the content types that are modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. - name: end in: query required: false type: string format: date-time description: > Provide the date and time of when the last modifications were made to the content types that you want returned. When the order is ascending (default), the content types that are modified on or before this date and time are returned. When the order is descending, the content types that are modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ. - name: startId in: query required: false type: string description: > If start does not uniquely identify the result to start from, you can specify the UUID of the result as startId. - name: endId in: query required: false type: string description: > If end does not uniquely identify the result to end at, you can specify the UUID of the result as endId. - name: offset in: query description: >- Use the offset parameter to specify the number of type documents to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of type documents that are returned. type: number format: integer default: 50 required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line - name: pageMode in: query required: false type: string enum: - offset - deep description: | Specify the next and previous page link mode. * `offset` - (default) allows paging forward or backwards, but only a small number of times * `deep` - uses index keys to efficiently page through a large result set, but only in one direction - name: order in: query description: >- Specify whether you want the type documents to be returned in ascending/oldest-first (default) or descending/newest-first order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the content type fields that are specified here are returned for each result. Any type document field is a valid value and can be specified as a comma-separated list. type: string required: false - *ref_235 responses: '200': description: >- All content type documents that are requested are listed in the order of the last modified date. schema: *ref_236 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/types/views/by-name: get: tags: - Authoring types summary: Retrieve all types in the database with the specified name. description: >- Use the /types/views/by-name endpoint to retrieve all types from the database with the specified name.
User roles: admin, manager, editor, viewer parameters: - name: name in: query description: The name to query. required: true type: string - name: offset in: query description: >- Use the offset parameter to specify the number of types to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: Set the limit for the number of types that are returned. type: number format: integer default: 50 required: false - name: fields in: query description: >- Only the content type fields that are specified here are returned for each result. Any type document field is a valid value and can be specified as a comma-separated list. type: string required: false - name: format in: query required: false type: string enum: - feed - array - sequence description: | Specify the result format. * `feed` - (default) returns a wrapper with links * `array` - returns just the array of results * `sequence` - each result is a separate JSON document on a new line responses: '200': description: Success. schema: *ref_236 '400': description: Invalid name or Invalid input. schema: *ref_234 '403': description: The operation is not available based on the current tenant's tier. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/elementdefs/{id}': get: tags: - Authoring types summary: Retrieve an existing element definition. description: >- 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 parameters: - name: id in: path description: Provide the ID of the element definition that you want to retrieve. type: string required: true - name: fields in: query description: >- Only the element definition fields that are specified here are returned for each result. Any element definition field is a valid value and can be specified as a comma-separated list. type: string required: false - *ref_235 - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the element definition retrieved is the most recent version. If the element definition is the most recent version, the call returns a 304 ( Not modified) message instead of sending the element definition back. type: string required: false responses: '200': description: >- Successfully retrieved the element definition that matches the ID provided from the database. schema: *ref_68 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified. The Etag value that you provided in the If-Match parameter matches the recent document version. '404': description: >- The element definition with ID {id} was not found or the current tenant's database is not provisioned. schema: *ref_234 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/elementdefs: get: tags: - Authoring types summary: Retrieve all element definitions in the database. description: >- 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 parameters: - name: offset in: query description: >- Use the offset parameter to specify the number of element definitions to skip and return the rest. type: number format: integer default: 0 required: false - name: limit in: query description: >- Set the limit for the number of element definitions that are returned. type: number format: integer default: 50 required: false - name: order in: query description: >- Specify whether you want the element definitions to be returned in ascending or descending order. type: string enum: - ascending - descending default: ascending required: false - name: fields in: query description: >- Only the element definition fields that are specified here are returned for each result. Any element definition field is a valid value and can be specified as a comma-separated list. type: string required: false - *ref_235 responses: '200': description: Successfully lists all element definitions that are requested. schema: *ref_242 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/versions/{classification}/{id}': get: summary: Retrieve all versions for the specified authoring item. description: >- Use the /versions/{classification}/{id} endpoint to retrieve all the versions for the specified authoring item.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: >- Provide the ID of the authoring item that you want to retrieve versions for. type: string required: true - name: classification in: path description: >- Provide the classification of the authoring item that you want to retrieve versions for. type: string required: true tags: - Authoring version responses: '200': description: >- Successfully retrieved the API representation containing all the versions for the specified item. schema: *ref_243 '404': description: >- No versions found for item with ID {id} and classification {classification}. schema: *ref_244 '429': *ref_165 '503': description: >- Unable to retrieve the specified item's versions from the database as the service is unavailable. Try again later. schema: *ref_244 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer '/authoring/v1/versions/{classification}/{id}/{timestamp}': get: summary: Retrieve a specific version for a specific authoring item. description: >- Use the /versions/{classification}/{id}/{timestamp} endpoint to retrieve a specific version for the specified authoring item.
User roles: admin, manager, editor, viewer parameters: - name: id in: path description: >- Provide the ID of the authoring item that you want to retrieve a version for. type: string required: true - name: classification in: path description: >- Provide the classification of the authoring item that you want to retrieve a version for. type: string required: true - name: timestamp in: path description: >- Provide the ISO-8601 timestamp of the version that you want to retrieve. type: string format: date-time required: true tags: - Authoring version responses: '200': description: >- Successfully retrieved the API representation of the version that matches the parameters that you provided. schema: type: object '404': description: >- No versions found for item with ID {id} and classification {classification}. schema: *ref_244 '429': *ref_165 '503': description: >- Unable to retrieve the versions for the specified item from the database as the service is unavailable. Try again later. schema: *ref_244 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/versions/restore: post: summary: Restore a versioned item - currently supported for content and assets. description: >- 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 tags: - Authoring version parameters: - name: projectId in: query type: string description: Optional projectId that the item belongs to. required: false responses: '200': description: > A draft version already exists for the item and was used to restore the item's version. '201': description: > No draft version already existed for the item and a new draft item was created to restore the item's version. '429': *ref_165 '500': description: An error occurred during the restore process. schema: *ref_244 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin - manager - editor /authoring/v1/versions/policy: get: summary: Retrieve the current version policy. description: >- 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 tags: - Authoring version responses: '200': description: Successfully retrieved version policy. schema: *ref_245 '429': *ref_165 '503': description: >- Unable to retrieve the version-policy from the database as the service is unavailable. Try again later. schema: *ref_244 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer /authoring/v1/versions/policy/on: post: summary: Turn on the version-policy. description: 'Use this endpoint to turn on the version-policy.
User roles: admin' tags: - Authoring version responses: '204': description: Successfully set the version-policy status to "on". '429': *ref_165 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin /authoring/v1/versions/policy/off: post: summary: Turn off the version-policy. description: >- Use this endpoint to turn off the version-policy. It will also trigger the version clean-up.
User roles: admin tags: - Authoring version responses: '204': description: Successfully set the version-policy status to "off". '429': *ref_165 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin /authoring/v1/versions/policy/disable: post: summary: Disable the version-policy. description: 'Use this endpoint to disable the version-policy.
User roles: admin' tags: - Authoring version responses: '204': description: Successfully set the version-policy status to "disable". '429': *ref_165 default: description: Unexpected error. schema: *ref_244 x-ibm-dx-security-user-roles: - admin /authoring/v1/contextualsearch: get: tags: - Authoring context search x-ibm-dx-security-user-roles: - admin - manager - editor - viewer summary: Retrieve contextual search results from the authoring collection. description: >- 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 produces: - application/json parameters: - name: filter in: query description: >- Use the filter parameter to specify the type of contextual filters to apply, it can be used multiple times to apply multiple filters. required: false type: string format: string - name: position description: >- Provide the center point for a proximity search by using the format "latitude,longitude". in: query required: false type: string - name: distance in: query description: >- Provide the value for distance that specifies the bounding radius around the location. The default value is 5. required: false type: number format: double default: 5 - name: metric in: query description: | Provide the metric that is used for the distance value. Acceptable values are km (kilometers) and mi (miles). The default value is km. required: false type: string format: string default: km - name: accept-language in: header description: > Provide the ordered list of preferred languages in the request to filter the retrieved search results. This header must be provided if the filter to be applied is `accept-language` (a web browser would provide this header by default). required: false type: string format: string - name: similar-source-id in: query description: > Provide the ID (uuid) of the item on which to base the `similar` search. This parameter is required if the filter to be applied is `similar`. required: false type: string format: string - name: similar-source-classification in: query description: > Provide the classification of the item on which to base the `similar` search. For example, to specify an asset classification, use "asset". This parameter is required if the filter to be applied is `similar`. required: false type: string format: string - name: df description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: defType description: >- The Solr "defType" parameter. Specify defType=edismax to use the edismax query parser. in: query required: false type: string - name: facet description: >- The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters. in: query required: false type: string - name: facet.contains description: >- The Solr "facet.contains" parameter returns only facets that contain this term. in: query required: false type: string - name: facet.containsIgnoreCase description: >- The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied. in: query required: false type: string - name: facet.field description: >- The Solr "facet.field" parameter identifies a field to be used as a facet. in: query required: false type: string - name: facet.limit description: >- The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100. in: query required: false type: string - name: facet.offset description: >- The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0. in: query required: false type: string - name: facet.prefix description: >- The Solr "facet.prefix" parameter returns only facets with this prefix. in: query required: false type: string - name: facet.range description: The Solr "facet.range" parameter. in: query required: false type: string - name: facet.range.gap description: The Solr "facet.range.gap" parameter. in: query required: false type: string - name: facet.range.start description: The Solr "facet.range.start" parameter. in: query required: false type: string - name: facet.range.end description: The Solr "facet.range.end" parameter. in: query required: false type: string - name: fl description: >- The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields. in: query required: false type: string - name: fq description: >- The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string - name: f.. description: >- Many facet parameters can be overridden on a per-field basis by using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of five terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5". in: query required: false type: string - name: indent description: >- If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts to indent the XML response such that it is easier to read. The default behavior is not to indent the XML response. in: query required: false type: string - name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: true type: string - name: qf description: >- The Solr "qf" parameter is supported by the dismax or edismax query parser. in: query required: false type: string - name: rows description: >- The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000. in: query required: false type: integer - name: start description: >- The Solr "start" parameter specifies an offset into the responses which are returned and can be used for paging query results. Default value is 0. in: query required: false type: integer - name: sort description: >- The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. in: query required: false type: string responses: '200': description: >- Successfully returns the results from the authoring search service after it transforms the query based on the passed filters. headers: content-language: description: > The language of the returned search results when the accept-language filter is used. This header is not present if no results are found for any of the languages listed in the accept-language header. type: string schema: type: object properties: query: type: string examples: application/json: response: numFound: 359 documents: - id: '21' type: article title: esse anim mollit description: >- Commodo excepteur commodo velit aliqua sunt proident mollit. owner: Harrell Stanton locale: en_GB locations: - -133.250593 - -19.598289 city: Savannah country: Germany demographic: teenager device: desktop creationDate: '2001-06-09T15:07:30.000Z' lastModifiedDate: '2001-06-09T15:07:30.000Z' _version_: '1537298216475688960' '400': description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. schema: type: object properties: error: type: string examples: application/json: service: prod-contextual-content-service requestId: '1983000440420008' errors: code: 101 message: Error running query. level: ERROR description: >- Unable to complete the query due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en '429': *ref_165 default: description: >- Unable to complete your request due to an unexpected error. Try again later. schema: *ref_246 examples: application/json: service: prod-contextual-content-service requestId: '455478465455511' errors: code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en /delivery/v1/contextualsearch: get: tags: - Delivery context search x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Retrieve contextual search results from the delivery collection description: >- 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 produces: - application/json parameters: - name: filter in: query description: >- Use the filter parameter to specify the type of contextual filters to apply, it can be used multiple times to apply multiple filters. required: false type: string format: string - name: position description: >- Provide the center point for a proximity search by using the format "latitude,longitude". in: query required: false type: string - name: distance in: query description: >- Provide the value for distance that specifies the bounding radius around the location. The default value is 5. required: false type: number format: double default: 5 - name: metric in: query description: | Provide the metric that is used for the distance value. Acceptable values are km (kilometers) and mi (miles). The default value is km. required: false type: string format: string default: km - name: accept-language in: header description: > Provide the ordered list of preferred languages in the request to filter the retrieved search results. This header must be provided if the filter to be applied is `accept-language` (a web browser would provide this header by default). required: false type: string format: string - name: similar-source-id in: query description: > Provide the ID (uuid) of the item on which to base the `similar` search. This parameter is required if the filter to be applied is `similar`. required: false type: string format: string - name: similar-source-classification in: query description: > Provide the classification of the item on which to base the `similar` search. For example, to specify an asset classification, use "asset". This parameter is required if the filter to be applied is `similar`. required: false type: string format: string - name: df description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: defType description: >- The Solr "defType" parameter. Specify defType=edismax to use the edismax query parser. in: query required: false type: string - name: facet description: >- The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters. in: query required: false type: string - name: facet.contains description: >- The Solr "facet.contains" parameter returns only facets that contain this term. in: query required: false type: string - name: facet.containsIgnoreCase description: >- The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied. in: query required: false type: string - name: facet.field description: >- The Solr "facet.field" parameter identifies a field to be used as a facet. in: query required: false type: string - name: facet.limit description: >- The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100. in: query required: false type: string - name: facet.offset description: >- The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0. in: query required: false type: string - name: facet.prefix description: >- The Solr "facet.prefix" parameter returns only facets with this prefix. in: query required: false type: string - name: facet.range description: The Solr "facet.range" parameter. in: query required: false type: string - name: facet.range.gap description: The Solr "facet.range.gap" parameter. in: query required: false type: string - name: facet.range.start description: The Solr "facet.range.start" parameter. in: query required: false type: string - name: facet.range.end description: The Solr "facet.range.end" parameter. in: query required: false type: string - name: fl description: >- The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields. in: query required: false type: string - name: fq description: >- The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string - name: f.. description: >- Many facet parameters can be overridden on a per-field basis by using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of five terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5". in: query required: false type: string - name: indent description: >- If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts to indent the XML response such that it is easier to read. The default behavior is not to indent the XML response. in: query required: false type: string - name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: true type: string - name: qf description: >- The Solr "qf" parameter is supported by the dismax or edismax query parser. in: query required: false type: string - name: rows description: >- The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000. in: query required: false type: integer - name: start description: >- The Solr "start" parameter specifies an offset into the responses which are returned and can be used for paging query results. Default value is 0. in: query required: false type: integer - name: sort description: >- The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. in: query required: false type: string responses: '200': description: >- Successfully returns the results from the delivery search service after it transforms the query based on the passed filters. headers: content-language: description: > The language of the returned search results when the accept-language filter is used. This header is not present if no results are found for any of the languages listed in the accept-language header. type: string schema: type: object properties: query: type: string examples: application/json: response: numFound: 359 documents: - id: '21' type: article title: esse anim mollit description: >- Commodo excepteur commodo velit aliqua sunt proident mollit. owner: Harrell Stanton locale: en_GB locations: - -133.250593 - -19.598289 city: Savannah country: Germany demographic: teenager device: desktop creationDate: '2001-06-09T15:07:30.000Z' lastModifiedDate: '2001-06-09T15:07:30.000Z' _version_: '1537298216475688960' '400': description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. schema: *ref_246 examples: application/json: service: prod-contextual-content-service requestId: '1983000440420008' errors: code: 101 message: Error running query. level: ERROR description: >- Unable to complete the query due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en '429': *ref_165 default: description: >- Unable to complete your request due to an unexpected error. Try again later. schema: *ref_246 examples: application/json: service: prod-contextual-content-service requestId: '455478465455511' errors: code: 5004 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en /delivery/v1/content/bulk_retrieve: post: tags: - Delivery content x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Retrieve filtered content by id in bulk description: >- 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 consumes: - application/json produces: - application/json parameters: - *ref_247 - *ref_248 responses: '200': *ref_249 '400': *ref_250 '429': *ref_165 default: *ref_251 /mydelivery/v1/content/bulk_retrieve: post: tags: - Delivery content x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: >- Retrieve filtered content items by id in bulk, including restricted ones. description: >- 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 consumes: - application/json produces: - application/json parameters: - *ref_247 - *ref_248 responses: '200': *ref_249 '400': *ref_250 '429': *ref_165 default: *ref_251 '/delivery/v1/content/{id}': get: tags: - Delivery content x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Get content item description: >- 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 produces: - application/json parameters: - *ref_252 - *ref_253 - *ref_254 responses: '200': *ref_255 '304': *ref_256 '400': *ref_257 '404': *ref_258 '429': *ref_165 default: *ref_251 '/mydelivery/v1/content/{id}': get: tags: - Delivery content x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: 'Get content item, including restricted ones.' description: >- 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 produces: - application/json parameters: - *ref_252 - *ref_253 - *ref_254 responses: '200': *ref_255 '304': *ref_256 '400': *ref_257 '404': *ref_258 '429': *ref_165 default: *ref_251 '/delivery/v1/rendering/render/content/{id}': get: summary: Applies server-side rendering to the specified content item description: >- Applies server-side rendering to the specified content item
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - text/html parameters: - *ref_259 - *ref_260 - *ref_261 - *ref_262 - *ref_263 responses: '200': description: Successfully retrieved the rendering. schema: type: string '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] tags: - Delivery render '/delivery/v1/rendering/sites/{id}': get: produces: - application/json summary: Delivery Site By ID description: >- Provides delivery site information including site metadata and pages hierarchy
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous parameters: - *ref_259 - *ref_262 responses: '200': description: Successful operation schema: type: object items: *ref_265 '304': description: Not modified '404': description: >- The delivery site information for the specified site ID was not found. schema: *ref_264 '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] tags: - Delivery render '/delivery/v1/rendering/context/{id}': get: produces: - application/json summary: Delivery Rendering Context By ID description: >- 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 parameters: - *ref_259 - *ref_262 responses: '200': description: Successfully retrieved the delivery rendering context. schema: type: object items: *ref_83 '304': description: Not modified '404': description: The delivery rendering context for the specified ID was not found. schema: *ref_264 '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] tags: - Delivery render '/delivery/v1/rendering/type/{id}': get: produces: - application/json summary: Aggregated type information by ID description: >- Aggregated type information by ID
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous parameters: - *ref_259 - *ref_262 responses: '200': description: Successfully retrieved the delivery type information. schema: type: object items: *ref_83 '304': description: Not modified '404': description: The delivery type for the specified ID was not found. schema: *ref_264 '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] tags: - Delivery render /delivery/v1/rendering/search: get: summary: Delivery Rendering Contexts By Search Query description: >- 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 classification content. - The results of the query are rendering contexts (0-*) in any case.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - application/json parameters: - *ref_266 - *ref_267 - *ref_262 responses: '200': description: Successfully retrieved the delivery rendering context. schema: type: array items: *ref_268 '304': description: Not modified '404': description: >- The delivery rendering context for the specified search query was not found. schema: *ref_264 '429': *ref_165 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] tags: - Delivery render '/mydelivery/v1/rendering/render/content/{id}': get: summary: Applies server-side rendering to the specified content item description: >- Applies server-side rendering to the specified content item
User roles: admin, manager, editor, viewer, authenticatedVisitor produces: - text/html parameters: - *ref_259 - *ref_260 - *ref_261 - *ref_262 - *ref_263 responses: '200': description: Successfully retrieved the rendering. schema: type: string '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor tags: - Delivery render '/mydelivery/v1/rendering/type/{id}': get: produces: - application/json summary: Aggregated type information by ID description: >- Aggregated type information by ID
User roles: admin, manager, editor, viewer, authenticatedVisitor parameters: - *ref_259 - *ref_262 responses: '200': description: Successfully retrieved the delivery type information. schema: type: object items: *ref_83 '304': description: Not modified '404': description: The delivery type for the specified ID was not found. schema: *ref_264 '429': *ref_165 '500': description: Server Error schema: *ref_264 x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor tags: - Delivery render /delivery/v1/resources: get: tags: - Delivery resources x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Retrieve a resource by path. description: >- 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 produces: - file - application/json parameters: - *ref_269 responses: '200': *ref_270 '404': *ref_271 '429': *ref_165 default: *ref_272 '/delivery/v1/resources/{fileIdentifier}': get: tags: - Delivery resources x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Retrieve a resource by Id. description: >- 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 produces: - file - application/json parameters: - *ref_273 responses: '200': *ref_270 '404': *ref_274 '429': *ref_165 default: *ref_272 /delivery/v1/search: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous tags: - Delivery search summary: Search in the delivery collection description: >- 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 Content returns in the result of a query. * **Solr Field Type:** This column specifies how Content 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 Content 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 addressed 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 Acoustic 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}/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 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}/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 Content 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 produces: - application/json parameters: - name: defType description: >- The Solr "defType" parameter. Specify "defType=edismax" to use the edismax query parser. in: query required: false type: string - name: df description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: facet description: >- The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters. in: query required: false type: string - name: facet.contains description: >- The Solr "facet.contains" parameter returns only facets containing this term. in: query required: false type: string - name: facet.containsIgnoreCase description: >- The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied. in: query required: false type: string - name: facet.field description: >- The Solr "facet.field" parameter identifies a field to be used as a facet. in: query required: false type: string - name: facet.limit description: >- The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100. in: query required: false type: string - name: facet.offset description: >- The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0. in: query required: false type: string - name: facet.prefix description: >- The Solr "facet.prefix" parameter returns only facets with this prefix. in: query required: false type: string - name: facet.range description: The Solr "facet.range" parameter. in: query required: false type: string - name: facet.range.end description: The Solr "facet.range.end" parameter. in: query required: false type: string - name: facet.range.gap description: The Solr "facet.range.gap" parameter. in: query required: false type: string - name: facet.range.start description: The Solr "facet.range.start" parameter. in: query required: false type: string - name: fl description: >- The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields that are highlighted in the "Stored" column of the table at the beginning of this document. in: query required: false type: string - name: fq description: >- The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string - name: f.. description: >- Many "facet" parameters can be overridden on a per-field basis using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of 5 terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5". in: query required: false type: string - name: indent description: >- If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts at indenting the XML response such that it is easier to read. The default behavior is not to indent the XML response. in: query required: false type: string - name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: false type: string - name: qf description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: rows description: >- The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000. in: query required: false type: integer - name: sort description: >- The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. in: query required: false type: string - name: start description: >- The Solr "start" parameter specifies an offset into the responses, which are returned and can be used for paging query results. Default value is 0. in: query required: false type: integer responses: '200': description: >- See the description above for examples of response data for different queries. '400': schema: *ref_275 description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. '404': schema: *ref_275 description: Not found - The delivery collection was not found. '414': schema: *ref_275 description: >- The request URL that addresses the search service is larger than the supported size of 4,096 bytes. Reduce the length of the query. '429': *ref_165 '500': schema: *ref_275 description: >- Internal server error - Unable to complete your request due to an exception. Try again later. /mydelivery/v1/search: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor tags: - Delivery search summary: Search in the delivery collection description: >- 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 Content returns in the result of a query. * **Solr Field Type:** This column specifies how Content 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 Content 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 query. ##### *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 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}/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 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}/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 Content 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 produces: - application/json parameters: - name: defType description: >- The Solr "defType" parameter. Specify "defType=edismax" to use the edismax query parser. in: query required: false type: string - name: df description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: facet description: >- The Solr "facet" parameter enables faceted search. Always set this parameter to true if you are using the other "facet" parameters. in: query required: false type: string - name: facet.contains description: >- The Solr "facet.contains" parameter returns only facets containing this term. in: query required: false type: string - name: facet.containsIgnoreCase description: >- The Solr "facet.containsIgnoreCase" parameter ignores case when the "facet.contains" parameter is applied. in: query required: false type: string - name: facet.field description: >- The Solr "facet.field" parameter identifies a field to be used as a facet. in: query required: false type: string - name: facet.limit description: >- The Solr "facet.limit" parameter specifies a limit for the number of results that are returned for each facet. Default value is 100. in: query required: false type: string - name: facet.offset description: >- The Solr "facet.offset" parameter specifies an offset into the facet results that are returned and can be used for paging facet results. Default value is 0. in: query required: false type: string - name: facet.prefix description: >- The Solr "facet.prefix" parameter returns only facets with this prefix. in: query required: false type: string - name: facet.range description: The Solr "facet.range" parameter. in: query required: false type: string - name: facet.range.end description: The Solr "facet.range.end" parameter. in: query required: false type: string - name: facet.range.gap description: The Solr "facet.range.gap" parameter. in: query required: false type: string - name: facet.range.start description: The Solr "facet.range.start" parameter. in: query required: false type: string - name: fl description: >- The Solr "fl" parameter defines the fields that are returned in the response. By default, the search service returns all fields that are highlighted in the "Stored" column of the table at the beginning of this document. in: query required: false type: string - name: fq description: >- The Solr "fq" parameter applies a filter query to the search results. in: query required: false type: string - name: f.. description: >- Many "facet" parameters can be overridden on a per-field basis using the syntax "f..=". For example, to specify a general limit of 10 terms for all facet fields and a specific limit of 5 terms for only the "category" facet field, use "facet.limit=10" and "f.category.facet.limit=5". in: query required: false type: string - name: indent description: >- If the Solr "indent" parameter is not "off" and has a non-blank value, then Solr attempts at indenting the XML response such that it is easier to read. The default behavior is not to indent the XML response. in: query required: false type: string - name: q description: The Solr "q" parameter uses Solr/Lucene standard query syntax. in: query required: false type: string - name: qf description: >- Either the Solr "df" or "qf" parameter is required. The parameter is supported by the edismax query parser. in: query required: false type: string - name: rows description: >- The Solr "rows" parameter controls how many documents are returned at the most, and can be used for paging query results. The default value is 10. The maximum allowed value is 1000. in: query required: false type: integer - name: sort description: >- The Solr "sort" parameter controls sorting of the query response. Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. It's recommended to sort by unique field or a combination ex. sort=lastModified desc, status desc. in: query required: false type: string - name: start description: >- The Solr "start" parameter specifies an offset into the responses, which are returned and can be used for paging query results. Default value is 0. in: query required: false type: integer responses: '200': description: >- See the description above for examples of response data for different queries. '400': schema: *ref_275 description: >- Bad request - Unable to complete your request due to missing parameters. Provide all required parameters and try again. '404': schema: *ref_275 description: Not found - The delivery collection was not found. '414': schema: *ref_275 description: >- The request URL that addresses the search service is larger than the supported size of 4,096 bytes. Reduce the length of the query. '429': *ref_165 '500': schema: *ref_275 description: >- Internal server error - Unable to complete your request due to an exception. Try again later. '/delivery/v1/sites/{siteId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Get the site descriptor of a public site description: >- Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - application/json parameters: - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_276 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: | Bad request. This error status is returned if a parameter value is invalid. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: | Unexpected error An internal error has occurred. For example, a dependent service is not running. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/mydelivery/v1/sites/{siteId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: Get the site descriptor of a public or protected site. description: |- Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor produces: - application/json parameters: - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_276 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: | Bad request. This error status is returned if a parameter value is invalid. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: | Unexpected error An internal error has occurred. For example, a dependent service is not running. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/delivery/v2/sites/{siteId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Get the site descriptor of a public site description: >- Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - application/json parameters: - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_278 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: | Bad request. This error status is returned if a parameter value is invalid. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: | Unexpected error An internal error has occurred. For example, a dependent service is not running. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/mydelivery/v2/sites/{siteId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: Get the site descriptor of a public or protected site. description: |- Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor produces: - application/json parameters: - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_278 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: | Bad request. This error status is returned if a parameter value is invalid. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: | Unexpected error An internal error has occurred. For example, a dependent service is not running. schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/delivery/v1/sites/{siteId}/pages/{pageId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Get the descriptor of a public page from a site. description: >- 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 produces: - application/json parameters: - name: pageId in: path description: The ID of the page item. required: true type: string format: uuid - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_89 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: Bad request schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/mydelivery/v1/sites/{siteId}/pages/{pageId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: Get the descriptor of a public or protected page from a site. description: >- 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 produces: - application/json parameters: - name: pageId in: path description: The ID of the page item. required: true type: string format: uuid - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_89 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: Bad request schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '404': description: Not found schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7003 message: 'Site not found for id : f54e763a-fd53-424b-8ad9-7cc690cca2dc.' level: ERROR description: A site item with the specified ID was not found in the system. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/delivery/v1/sites/{siteId}/pages/by-parent/{parentPageId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous x-ibm-dx-vary: [] summary: Get all public child pages of a specified parent page description: >- 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 produces: - application/json parameters: - name: parentPageId in: path description: >- The ID of the parent page item, or *@top* to retrieve the top-level pages. required: true type: string format: uuid - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: count in: query description: >- specifies the maximum number of items that should be returned in this request. If this parameter is not specified, up to 100 page items are returned. required: false type: number - name: start in: query description: >- specifies the starting offset of the result set being returned. For example, if the value of this parameter is 5, the first 5 items in the result set are ignored. If this parameter is not specified, the starting offset of the result set is 0. required: false type: number - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_279 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: Bad request schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites '/mydelivery/v1/sites/{siteId}/pages/by-parent/{parentPageId}': get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor summary: Get all public or protected child pages of a specified parent page description: >- 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 produces: - application/json parameters: - name: parentPageId in: path description: >- The ID of the parent page item, or *top* to retrieve the top-level pages. required: true type: string format: uuid - name: siteId in: path description: >- The ID of the site item, or `@current` to indicate that the ID of the site is derived from the addressed URL via custom domain site mapping or URL path-based site addressing. For further details consult the Content documentation. required: true type: string format: uuid - name: fields in: query description: >- Reduce the returned content down to just the specified fields. Fields specified by a comma-separated list of field names and should only be used once in query string. To only retrieve `id` and `name` this parameter should look like `id,name`. Undefined fields are ignored. required: false type: string items: type: string collectionFormat: csv - name: count in: query description: >- specifies the maximum number of items that should be returned in this request. If this parameter is not specified, up to 100 page items are returned. required: false type: number - name: start in: query description: >- specifies the starting offset of the result set being returned. For example, if the value of this parameter is 5, the first 5 items in the result set are ignored. If this parameter is not specified, the starting offset of the result set is 0. required: false type: number - name: If-None-Match in: header description: >- The Etag value from a previous request to check whether a content item has been updated since, if so, a 304 (Not Modified) response code is returned instead of the content item. type: string required: false responses: '200': description: Success schema: *ref_279 headers: Etag: description: The Etag value identifies this site item for future requests. type: string '304': description: >- The "Not modified" message is returned when the If-None-Match header is used and the Etag value matches the most recent version of the content item. '400': description: Bad request schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 7001 message: Missing or invalid value for 'fields' query parameter. level: ERROR description: >- Check that the 'fields' parameter is not blank, does not contain spaces or empty values, e.g. 'fields=rev,,last-modified' is considered invalid. locale: en '429': *ref_165 default: description: Unexpected error schema: *ref_277 examples: application/json: service: prod-delivery-sites requestId: c39d3e05-22f7-4d7c-8d7b-21ba6a2db508 errors: code: 1014 message: Unexpected error occurred. level: ERROR description: >- Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists. locale: en tags: - Delivery sites /registry/v1/currenttenant: parameters: - in: header name: x-ibm-dx-tenant-id description: ID of Tenant required: true type: string get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Retrieve a tenant tags: - Tenant Registry description: >- ##### 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 produces: - application/json parameters: - name: fields in: query description: 'Return these JSON fields ex ?fields=id,name' required: false type: string responses: '200': description: Successful response schema: *ref_280 '400': description: Error response schema: *ref_281 '404': description: Indicates the tenant does not exist schema: *ref_281 '429': *ref_165 put: x-ibm-dx-security-user-roles: - admin x-ibm-dx-operator-entrypoint-roles: - system tags: - Tenant Registry summary: Update a tenant description: >- ##### 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 consumes: - application/json produces: - application/json parameters: - in: body name: tenant_definition description: Definition of the new tenant required: true schema: *ref_282 responses: '200': description: Successful response schema: *ref_280 '400': description: Error response schema: *ref_281 '404': description: Indicates the tenant does not exist schema: *ref_281 '429': *ref_165 /login/v1/removecookies: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Remove tenant and auth cookie. description: >- Endpoint to receive a set-cookie cleaning the authentication and tenant cookies for the actual domain.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - application/json responses: '200': description: Cleaning the cookies headers: set-cookie: description: Sending cookies to client type: string set-cookie2: description: Sending cookies to client type: string schema: *ref_283 '429': *ref_165 tags: - Login service /login/v1/basicauth: get: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Userid and password login using GET operation description: >- 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 produces: - application/json parameters: - name: Authorization in: header description: Login credentials as basicAuthentication header required: true type: string - name: accept-privacy-notice in: query description: (Optional) To accept the latest privacy notice. type: string default: empty responses: '200': description: Success for login. schema: *ref_284 headers: x-ibm-dx-tenant-id: description: Sending tenant-id to client type: string x-ibm-dx-tenant-locale: description: Sending tenant-locale to client type: string x-ibm-dx-tenant-base-url: description: Sending tenant-base-url to client type: string set-cookie: description: Sending cookies to client type: string set-cookie2: description: Sending cookies to client type: string '401': description: Authentication failed with credentials (incorrect or missing) schema: *ref_283 '403': description: Access forbidden (e.g. no access to tenant or enterprise federation) schema: *ref_283 '404': description: Tenant not found schema: *ref_283 '412': description: Precondition Failed for credentials (incorrect format or missing) schema: *ref_283 '423': description: The tenant is locked schema: *ref_283 '429': *ref_165 '503': description: Downstream service not available (e.g. Acoustic ID) schema: *ref_283 tags: - Login service post: x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Userid and password login using POST operation description: >- 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 produces: - application/json parameters: - name: Authorization in: header description: Login credentials as basicAuthentication header required: false type: string - name: accept-privacy-notice in: query description: (Optional) To accept the latest privacy notice. type: string default: empty responses: '200': description: Success for login. schema: *ref_284 headers: x-ibm-dx-tenant-id: description: Sending tenant-id to client type: string x-ibm-dx-tenant-locale: description: Sending tenant-locale to client type: string x-ibm-dx-tenant-base-url: description: Sending tenant-base-url to client type: string set-cookie: description: Sending cookies to client type: string set-cookie2: description: Sending cookies to client type: string '401': description: Authentication failed with credentials (incorrect or missing) schema: *ref_283 '403': description: Access forbidden (e.g. no access to tenant or enterprise federation) schema: *ref_283 '404': description: Tenant not found schema: *ref_283 '412': description: Precondition Failed for credentials (incorrect format or missing) schema: *ref_283 '423': description: The tenant is locked schema: *ref_283 '429': *ref_165 '503': description: Downstream service not available (e.g. Acoustic ID) schema: *ref_283 tags: - Login service /user-profile/v1/users/currentuser: get: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin - manager - editor - viewer - authenticatedVisitor - anonymous summary: Find the current user description: >- Returns the current user
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous produces: - application/json parameters: - *ref_285 responses: '200': description: Returns the current user schema: *ref_286 '400': description: Response indicating a client error schema: *ref_287 '429': *ref_165 /user-profile/v1/users: parameters: [] get: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin summary: Find all users. description: >- Returns an array containing all users matching the query.
User roles: admin produces: - application/json parameters: - *ref_288 - *ref_289 - *ref_290 - *ref_291 - *ref_292 responses: '200': description: >- Returns a (sub-)list of all available users. At most [limit] items are returned. schema: type: object allOf: - *ref_293 required: - items properties: items: type: array items: *ref_286 '400': description: Response indicating a client error. schema: *ref_287 '429': *ref_165 post: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin summary: Add a new user. description: 'Adds a new user and returns the user object.
User roles: admin' consumes: - application/json produces: - application/json parameters: - in: body name: body description: User object that needs to be added. required: true schema: *ref_294 responses: '201': description: User was created successfully. schema: *ref_286 '400': description: Response indicating a client error. schema: *ref_287 '409': description: A user with the same externalID already exists. schema: *ref_287 '429': *ref_165 '/user-profile/v1/users/{id}': parameters: - *ref_295 get: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin summary: Find user by ID. description: 'Returns a single user.
User roles: admin' produces: - application/json parameters: - in: path name: id description: >- The unique internal identifier of the entity that should be processed or the special value currentuser that uses the ID provided in the userID header. required: true type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|currentuser - *ref_289 - *ref_285 responses: '200': description: Returns the user object for the given user. schema: *ref_296 '400': description: Response indicating a client error. schema: *ref_287 '404': description: The given ID cannot be resolved. '429': *ref_165 put: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin summary: Update an existing user. description: >- Updates an existing user and returns the updated user object.
User roles: admin consumes: - application/json produces: - application/json parameters: - in: body name: body description: >- The existing user object is replaced by the given object. Some fields will be ignored. required: true schema: *ref_297 responses: '200': description: The user was updated successfully. schema: *ref_286 '400': description: Response indicating a client error. schema: *ref_287 '404': description: The given ID cannot be resolved. '429': *ref_165 delete: tags: - Administering user profiles x-ibm-dx-security-user-roles: - admin summary: Delete an existing user. description: 'Deletes an existing user.
User roles: admin' produces: - application/json parameters: - in: path name: id description: >- The unique internal identifier of the entity that should be processed or the special value currentuser that uses the ID provided in the userID header. required: true type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|currentuser - *ref_289 responses: '204': description: User was deleted successfully. '400': description: Response indicating a client error. schema: *ref_287 '404': description: The given ID cannot be resolved. '429': *ref_165 /webhook/v1/profile: get: summary: Retrieves the webhook profile for the current tenant description: >- Use the /profile end-point to retrieve the webhook profile from the database.
User roles: admin parameters: - name: fields in: query description: >- Only the content type fields that are specified here are returned for each result. Any type document field is a valid value and can be specified as a comma-separated list. type: string required: false - name: If-None-Match in: header description: >- Provide an Etag value from a previous request to check whether the webhook profile retrieved is the most recent version. If the webhook is the most recent version, the call returns a 304 ( Not modified) message instead of sending the webhook profile back. type: string required: false responses: '200': description: Success. schema: *ref_298 headers: Etag: description: The Etag value helps identify this document in future requests. type: string '304': description: >- Not modified is returned when using If-None-Match header and the value matches the latest version of the item. '404': description: There is no existing webhook profile. schema: *ref_299 '429': *ref_165 x-ibm-dx-security-user-roles: - admin tags: - Webhook profiles put: summary: Creates or updates the webhook profile for the current tenant description: >- 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 parameters: - name: body in: body description: Contains the webhook profile to save. required: true schema: *ref_298 responses: '200': description: Success. schema: *ref_298 '400': description: Invalid input. schema: *ref_299 '401': description: The user is not authorized to run this action. schema: *ref_299 '429': *ref_165 '500': description: Unexpected error. schema: *ref_299 x-ibm-dx-security-user-roles: - admin tags: - Webhook profiles delete: summary: Deletes the webhook profile for the current tenant. description: >- Use the /profile endpoint to delete the webhook profile from the database.
User roles: admin responses: '200': description: Success. '401': description: The user is not authorized to run this action. schema: *ref_299 '404': description: There is no existing webhook profile. schema: *ref_299 '429': *ref_165 '500': description: Unexpected error. schema: *ref_299 x-ibm-dx-security-user-roles: - admin tags: - Webhook profiles /publishing/v1/jobs: x-ibm-dx-security-user-roles: - admin - manager post: tags: - Publishing summary: Create a job description: >- 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 parameters: - name: newJob in: body required: false schema: *ref_300 responses: '201': description: Successfully triggered a new job. schema: *ref_143 '400': *ref_301 '429': *ref_165 /publishing/v1/jobs/current-job: x-ibm-dx-security-user-roles: - admin - manager get: x-ibm-dx-security-user-roles: - admin - manager - editor tags: - Publishing summary: Retrieve an existing job description: >- Use the /jobs/current-job endpoint to retrieve current-job from the database.
User roles: admin, manager, editor responses: '200': description: Successfully retrieved a current-job. schema: *ref_143 headers: Content-Location: description: >- Provide the URL of the actual revision of the job that is returned. type: string '400': description: >- Unable to handle the request as it does not match the API definition. schema: *ref_120 '404': description: current-job was not found. schema: *ref_120 '429': *ref_165 /publishing/v1/jobs/current-job/status: x-ibm-dx-security-user-roles: - admin - manager get: x-ibm-dx-security-user-roles: - admin - manager - editor tags: - Publishing summary: Retrieve the status of current-job description: >- Use the /jobs/current-job/status endpoint to retrieve the status information for the current-job.
User roles: admin, manager, editor responses: '200': description: Successfully retrieved the status for the current-job. schema: *ref_302 '400': description: >- Unable to handle the request as it does not match the API definition. schema: *ref_120 '404': description: The status for the current-job. schema: *ref_120 '429': *ref_165 /publishing/v1/site-revisions/default: x-ibm-dx-security-user-roles: - admin - manager get: x-ibm-dx-security-user-roles: - admin - manager - editor tags: - Publishing summary: Get the default site revision description: >- Use the /site-revisions/default endpoint to retrieve the default site revision
User roles: admin, manager, editor parameters: - *ref_303 responses: '200': description: The default site revision schema: *ref_145 headers: Content-Location: description: URL of the actual revision of the returned item type: string '400': description: >- Unable to handle the request as it does not match the API definition. schema: *ref_120 '429': *ref_165 put: tags: - Publishing summary: Update the default site revision description: >- 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 Content immediately but with a time lag of up to 30 seconds
User roles: admin, manager parameters: - name: siteRevision in: body required: true schema: *ref_304 responses: '200': description: Successfully updated the site revision. schema: *ref_153 '400': description: >- Unable to handle the request as it does not match the API definition. schema: *ref_120 '409': description: Response indicating that the site revision cannot be activated schema: *ref_120 '429': *ref_165