---
updatedAt: 2026-04-08T10:21:42.000Z
agentTools:
projectIndex: https://developer.goacoustic.com/acoustic-content/llms.txt
---
# Retrieve an existing element definition.
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
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.142",
"x-ibm-name": "ibm-watson-content-hub-api",
"title": "Acoustic Content API",
"description": "Copyright © Acoustic, L.P. 2019"
},
"tags": [
{
"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.\n\nNote: Documents created or updated in the old 1.0 format will be migrated to the 1.1 format on save.\n"
}
],
"paths": {
"/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.\n\nEach element definition describes a variety of element that can be added to a content type.\n\nTo programmatically create a content-type, merge the 'elementFragment' attribute into the 'elements' attribute of the type, performing the following replacements:\n '$ELEMENT_KEY$': With the desired element key\n '$ELEMENT_LABEL$': With the desired element label\n
User roles: admin, manager, editor, viewer",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Provide the ID of the element definition that you want to retrieve.",
"required": true,
"schema": {
"type": "string"
}
},
{
"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.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "include",
"in": "query",
"description": "Specify additional fields to include with each result.\nValid options are:\n * links: Adds the 'links' section (see '#/definitions/DocumentLinks') to the response.\n * all: Adds all current and future additional fields to the response.\n\nWhen 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.\n",
"required": false,
"schema": {
"type": "string"
}
},
{
"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.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved the element definition that matches the ID provided from the database.",
"headers": {
"Etag": {
"description": "The Etag value helps identify this document in future requests.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"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": {
"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": {
"type": "string",
"description": "the workflow status.",
"enum": [
"draft",
"ready",
"retired"
]
},
"elementFragment": {
"type": "object",
"description": "The templated the current element.",
"properties": {
"key": {
"type": "string"
},
"type": {
"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.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"errors": {
"type": "array",
"items": {
"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."
}
}
}
}
}
},
"429": {
"description": "Too Many Requests, the server has reached a limit, the request must be sent again at a later time.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-ibm-dx-security-user-roles": [
"admin",
"manager",
"editor",
"viewer"
]
}
}
},
"components": {
"schemas": {
"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"
]
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```