Entity metadata reference

The public REST API is fully metadata-driven. All entities described by metadata resources can be accessed using the REST API as resource collection.

Note: This API supports only the GET operation.

URI

The table below lists the URIs for the different levels.

Level URI
Workspace

http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/entities

Shared space

http[s]://<server>:<port>/api/shared_spaces/<space_id>/metadata/entities

Notes

  • The URI supports filtering by name.

  • For the syntax for specifying parameters in URIs, see Variables and values.

Properties

The table below provides a description of entity properties included in the metadata response.

Property Description
Name

The entity's API name.
Features

Array of features supported by the entity. For details, see Features below.
Description

A description of the entity.
Label

The entity's display name.

Features

Features are capabilities supported by the entity. The following table lists all possible features. The features are included in the entity metadata according to their availability.

Feature Description
REST The REST API methods supported by the entity, and their support level.
Mailing The entity supports email notifications, exposed through a mails sub-resource. For details, see Send an email.
Non-auditable The entity is excluded from audit logs. For details, see Audit entities (technical preview).
History The entity is included when retrieving entity history via the REST API. For details, see View history (technical preview).
Drafts The entity supports creation in draft mode. For details, see Drafts below.
Attachments The entity supports attachments. For details, see Attachments below.
Comments The entity supports comments. For details, see Comments below.
Business rules The entity supports business rules.
Subtypes The entity has subtypes. For example, work_item has the subtypes epic, feature, etc. The names subtypes are provided.
Subtype of The entity is a subtype of another entity. For example, defect is a subtype of work_item. The name of the supertype is provided.
Phases The entity supports workflow phases, enabling status transitions from phase to phase.
Hierarchy The entity is a member in a hierarchical tree. The following details are provided: parent_types, child_types, max_depth, root_entity.
User-defined fields The entity supports user-defined fields.

Drafts

The drafts feature indicates whether drafts of work items (epics, features, user stories, and defects) can be created.

Use drafts to bypass validation rules when POSTing work items using the API. This allows integrations using the API to quickly create work items without, for example, validating required fields.

If listed, indicates that the resource supports draft mode. For details, see Draft entities.

Attachments

If present in the resource's metadata, indicates that the resource supports attachments via the <context>/attachments API. To reference the owning entity, use the field owner_<entity name> on the attachment entity, where entity name is the entity's name or its parent type if it has the subtype_of feature (for example, owner_defect). The attachment entity can reference only one owner. The actual field name can be queried from the field metadata API; for details, see Field metadata reference.

Comments

The comments feature indicates whether the entity supports comments through the <context>/comments API.

Field Description
name

The name of the feature is a constant value: comments.

The actual field name can be queried via the field metadata API for the comment entity. For details, see Field metadata reference.

Example: owner_defect

The comment entity must have a reference to only one owner entity.
Copy code

Comments example:

{
    "name": "comments"
    "relation_name": "comments_to_epic"
}

Defect entity example

The entities resource returns metadata about the data returned for a member of a collection.

Copy code
Example showing the metadata for the Defect entity:
         {
            "features": [
                {
                    "parent_types": [
                        "feature",
                        "work_item_root"
                    ],
                    "max_depth": 4,
                    "root": {
                        "type": "work_item_root",
                        "id": "1001"
                    },
                    "name": "hierarchy",
                    "child_types": []
                },
                {
                    "methods": [
                        "DELETE",
                        "POST",
                        "GET",
                        "PUT"
                    ],
                    "name": "rest",
                    "url": "defects"
                },
                {
                    "name": "mailing",
                    "url": "mails"
                },
                {
                    "name": "attachments",
                },
                {
                    "name": "phases"
                },
                {
                    "name": "subtype_of",
                    "type": "work_item"
                },
                {
                    "name": "user_defined_fields"
                },
                {
                    "name": "comments",
                },
                {
                    "name": "business_rules"
                }
            ],
            "name": "defect",
            "description": "A problem detected in the application.",
            "label": "Defect",
            "type": "entity_metadata"
        },

See also