Add a readme

POST /api/meta/entity/bulk#addReadme

Attach a readme to an asset.

Note that the creation of a readme relies on no match being found for the provided qualifiedNames. If the qualifiedNames do match any existing readme, that readme will instead be updated rather than a new one being created. Also be aware that the qualifiedName is case-sensitive.

For more details on the semantics and other attributes available through this interface, see the Upsert entities operation.

Body Required

List of readmes (entities) and the asset to attach them to.

  • entities array[object] Required

    Instance of a readme in Atlan, with its detailed information.

    • attributes object Required

      Attributes that can exist in readmes in Atlan.

      • isGlobal boolean | null
      • reference string | null
      • qualifiedName string Required

        Unique name for this readme. This is usually the concatenation of the related asset's GUID with /readme.

      • name string Required

        Human-readable name of the readme. This is usually the concatenation of the related asset's name with Readme.

      • description string | null Required

        Contents of the readme. This should be a string of HTML that has been URL-encoded. For examples of the decoded form, run the example description value through urldecoder.org. For examples of an encoded form, write plain-text HTML into urlencoder.org.

    • typeName string Required

      Should always be Readme.

    • relationshipAttributes object | null Required

      Relationships that can exist across all readmes in Atlan.

      • asset object Required

        Asset to which this readme should be attached.

        • typeName string

          Should be some sub-type of Asset.

          Values are AtlasGlossary, AtlasGlossaryCategory, AtlasGlossaryTerm, Readme, Link, Insight, Query, Database, Schema, Table, View, MaterialisedView, Column, Procedure, TablePartition, LookerDashboard, LookerExplore, LookerField, LookerFolder, LookerLook, LookerModel, LookerProject, LookerQuery, LookerTile, PowerBIDashboard, PowerBIDataflow, PowerBIDataset, PowerBIDatasource, PowerBIPage, PowerBIReport, PowerBITile, PowerBIWorkspace, SalesforceDashboard, SalesforceField, SalesforceObject, SalesforceOrganization, SalesforceReport, TableauCalculatedField, TableauDashboard, TableauDatasource, TableauDatasourceField, TableauFlow, TableauMetric, TableauProject, TableauSite, TableauWorkbook, TableauWorksheet, ObjectStore, S3, S3Bucket, S3Object, DataStudioAsset, Process, BIProcess, or ColumnProcess.

        • guid string | null

          Unique identifier of the related object. If the uniqueAttributes are not provided, this must be provided.

        • uniqueAttributes object | null

          Attribute(s) that uniquely identify the related object. If the guid is not provided, these must be provided.

Responses

  • 200 object

    Readme(s) were successfully created and attached.

    • mutatedEntities object | null

      Assets that were changed.

      • CREATE array[object]

        Instance of an asset in Atlan, with its detailed information.

        • entity object

          Instance of an entity in Atlan, with its detailed information.

          • typeName string

            Name of the type definition that defines this instance.

          • attributes object | null

            Will be further documented in sub-types of EntityHeader.

          • classifications array[object] | null

            Instance of a classification in Atlan, with its detailed information.

            • typeName string

              Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

            • Unique identifier of the entity to which this classification is attached.

            • propagate boolean | null

              Whether to propagate this classification to other entities related to the entity to which the classification is attached.

            • Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

            • entityStatus string | null

              Status of the entity to which this classification is attached.

              Values are ACTIVE or DELETED.

          • displayText string | null

            Human-readable name of the entity.

          • guid string

            Unique identifier of the entity instance.

          • isIncomplete boolean | null

            Default value is false.

          • businessAttributes object | null

            Map of custom metadata attributes and values defined on the entity.

          • Map of relationships for the entity. The specific keys of this map will vary by type, so are described in the sub-types of this schema.

          • createdBy string | null

            Username of the user who created the object.

          • updatedBy string | null

            Username of the user who last updated the object.

          • createTime integer | null

            Time (epoch) at which this object was created, in milliseconds.

          • updateTime integer | null

            Time (epoch) at which this object was last updated, in milliseconds.

          • version integer | null

            Version of this object.

          • classificationNames array[string] | null

            List of classifications for this entity. Note that these are the internal hashed names used in Atlan, not the displayText of the classification.

          • labels array[string] | null

            Internal use only.

          • status string

            Status of the entity, either ACTIVE or DELETED.

            Values are ACTIVE or DELETED.

          • customAttributes object | null

            Internal use only.

          • pendingTasks array[string] | null

            Internal use only.

        • Map of related entities keyed by the GUID of the related entity. The values will be the detailed entity object of the related entity.

        • typeName string

          Name of the type definition that defines this instance.

        • attributes object | null

          Attributes that can exist across all assets in Atlan.

        • classifications array[object] | null

          Instance of a classification in Atlan.

          • typeName string

            Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

          • Unique identifier of the entity to which this classification is attached.

          • propagate boolean | null

            Whether to propagate this classification to other entities related to the entity to which the classification is attached.

          • Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

        • displayText string | null

          Human-readable name of the entity.

        • guid string

          Unique identifier of the entity instance.

        • isIncomplete boolean | null

          Default value is false.

        • businessAttributes object | null

          Map of custom metadata attributes and values defined on the entity.

        • Map of the relationships to this asset.

          • readme object

            Details to use within an asset when referring to a readme.

            • typeName string

              Should always be Readme.

            • guid string | null

              Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

          • meanings array[object]

            Details to use within an asset when referring to a term.

            • typeName string

              Should always be AtlasnGlossaryTerm.

            • guid string | null

              Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

              • Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

      • UPDATE array[object]

        Instance of an asset in Atlan, with its detailed information.

        • entity object

          Instance of an entity in Atlan, with its detailed information.

          • typeName string

            Name of the type definition that defines this instance.

          • attributes object | null

            Will be further documented in sub-types of EntityHeader.

          • classifications array[object] | null

            Instance of a classification in Atlan, with its detailed information.

            • typeName string

              Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

            • Unique identifier of the entity to which this classification is attached.

            • propagate boolean | null

              Whether to propagate this classification to other entities related to the entity to which the classification is attached.

            • Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

            • entityStatus string | null

              Status of the entity to which this classification is attached.

              Values are ACTIVE or DELETED.

          • displayText string | null

            Human-readable name of the entity.

          • guid string

            Unique identifier of the entity instance.

          • isIncomplete boolean | null

            Default value is false.

          • businessAttributes object | null

            Map of custom metadata attributes and values defined on the entity.

          • Map of relationships for the entity. The specific keys of this map will vary by type, so are described in the sub-types of this schema.

          • createdBy string | null

            Username of the user who created the object.

          • updatedBy string | null

            Username of the user who last updated the object.

          • createTime integer | null

            Time (epoch) at which this object was created, in milliseconds.

          • updateTime integer | null

            Time (epoch) at which this object was last updated, in milliseconds.

          • version integer | null

            Version of this object.

          • classificationNames array[string] | null

            List of classifications for this entity. Note that these are the internal hashed names used in Atlan, not the displayText of the classification.

          • labels array[string] | null

            Internal use only.

          • status string

            Status of the entity, either ACTIVE or DELETED.

            Values are ACTIVE or DELETED.

          • customAttributes object | null

            Internal use only.

          • pendingTasks array[string] | null

            Internal use only.

        • Map of related entities keyed by the GUID of the related entity. The values will be the detailed entity object of the related entity.

        • typeName string

          Name of the type definition that defines this instance.

        • attributes object | null

          Attributes that can exist across all assets in Atlan.

        • classifications array[object] | null

          Instance of a classification in Atlan.

          • typeName string

            Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

          • Unique identifier of the entity to which this classification is attached.

          • propagate boolean | null

            Whether to propagate this classification to other entities related to the entity to which the classification is attached.

          • Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

        • displayText string | null

          Human-readable name of the entity.

        • guid string

          Unique identifier of the entity instance.

        • isIncomplete boolean | null

          Default value is false.

        • businessAttributes object | null

          Map of custom metadata attributes and values defined on the entity.

        • Map of the relationships to this asset.

          • readme object

            Details to use within an asset when referring to a readme.

            • typeName string

              Should always be Readme.

            • guid string | null

              Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

          • meanings array[object]

            Details to use within an asset when referring to a term.

            • typeName string

              Should always be AtlasnGlossaryTerm.

            • guid string | null

              Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

              • Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

    • Map of assigned unique identifiers for the changed assets.

POST /api/meta/entity/bulk#addReadme
curl \
 -X POST https://tenant.atlan.com/api/meta/entity/bulk#addReadme \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"entities":[{"typeName":"Readme","attributes":{"name":"user_id Readme","qualifiedName":"2e5b4bdb-592d-4964-afbe-021214b0cc9f/readme\n","description":"%3Ch2%3EID%3C%2Fh2%3E%3Cp%3EUnique%20identifier%20of%20a%20customer.%3C%2Fp%3E"},"relationshipAttributes":{"asset":{"typeName":"Column","guid":"2e5b4bdb-592d-4964-afbe-021214b0cc9f"}}},{"typeName":"Readme","attributes":{"name":"INSTACART_TOP_USERS Readme","qualifiedName":"c1ef6535-4c9d-4946-83a3-9f70d7a98e47/readme","description":"%3Ch2%3EOverview%3C%2Fh2%3E%3Cp%3ETop%20users%20of%20our%20website.%3C%2Fp%3E"},"relationshipAttributes":{"asset":{"typeName":"Table","guid":"d45fb048-0461-44ec-9cc7-eaf7a438c8df"}}}]}'
Request example
{
  "entities": [
    {
      "typeName": "Readme",
      "attributes": {
        "name": "user_id Readme",
        "qualifiedName": "2e5b4bdb-592d-4964-afbe-021214b0cc9f/readme\n",
        "description": "%3Ch2%3EID%3C%2Fh2%3E%3Cp%3EUnique%20identifier%20of%20a%20customer.%3C%2Fp%3E"
      },
      "relationshipAttributes": {
        "asset": {
          "typeName": "Column",
          "guid": "2e5b4bdb-592d-4964-afbe-021214b0cc9f"
        }
      }
    },
    {
      "typeName": "Readme",
      "attributes": {
        "name": "INSTACART_TOP_USERS Readme",
        "qualifiedName": "c1ef6535-4c9d-4946-83a3-9f70d7a98e47/readme",
        "description": "%3Ch2%3EOverview%3C%2Fh2%3E%3Cp%3ETop%20users%20of%20our%20website.%3C%2Fp%3E"
      },
      "relationshipAttributes": {
        "asset": {
          "typeName": "Table",
          "guid": "d45fb048-0461-44ec-9cc7-eaf7a438c8df"
        }
      }
    }
  ]
}
Response example (200)
{
  "mutatedEntities": {
    "CREATE": [
      {
        "typeName": "Readme",
        "attributes": {
          "popularityScore": 1.17549435e-38,
          "viewerUsers": [],
          "sourceCreatedAt": 0,
          "viewScore": 1.17549435e-38,
          "lastSyncRunAt": 0,
          "adminRoles": [],
          "adminGroups": [],
          "qualifiedName": "2e5b4bdb-592d-4964-afbe-021214b0cc9f/readme",
          "__hasLineage": false,
          "description": "%3Ch2%3EID%3C%2Fh2%3E%3Cp%3EUnique%20identifier%20of%20a%20customer.%3C%2Fp%3E\n",
          "adminUsers": [],
          "ownerGroups": [],
          "isEditable": true,
          "sourceUpdatedAt": 0,
          "announcementUpdatedAt": 0,
          "name": "user_id Readme",
          "certificateUpdatedAt": 0,
          "isGlobal": false,
          "isDiscoverable": true,
          "viewerGroups": [],
          "ownerUsers": []
        },
        "guid": "2992ae78-c480-48b9-b61a-67cce210e3d7",
        "status": "ACTIVE",
        "displayText": "user_id Readme",
        "classificationNames": [],
        "classifications": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "createTime": 1655460145909,
        "updateTime": 1655460145909
      },
      {
        "typeName": "Readme",
        "attributes": {
          "popularityScore": 1.17549435e-38,
          "viewerUsers": [],
          "sourceCreatedAt": 0,
          "viewScore": 1.17549435e-38,
          "lastSyncRunAt": 0,
          "adminRoles": [],
          "adminGroups": [],
          "qualifiedName": "c1ef6535-4c9d-4946-83a3-9f70d7a98e47/readme",
          "__hasLineage": false,
          "description": "%3Ch2%3EOverview%3C%2Fh2%3E%3Cp%3ETop%20users%20of%20our%20website.%3C%2Fp%3E\n",
          "adminUsers": [],
          "ownerGroups": [],
          "isEditable": true,
          "sourceUpdatedAt": 0,
          "announcementUpdatedAt": 0,
          "name": "INSTACART_TOP_USERS Readme",
          "certificateUpdatedAt": 0,
          "isGlobal": false,
          "isDiscoverable": true,
          "viewerGroups": [],
          "ownerUsers": []
        },
        "guid": "f25aec9b-790f-4760-b66c-997eee2fe613",
        "status": "ACTIVE",
        "displayText": "INSTACART_TOP_USERS Readme",
        "classificationNames": [],
        "classifications": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "createTime": 1655460145909,
        "updateTime": 1655460145909
      }
    ],
    "UPDATE": [
      {
        "typeName": "Column",
        "attributes": {
          "qualifiedName": "default/snowflake/1655116256/ATLAN_SAMPLE_DATA/FOOD_BEVERAGE/INSTACART_TOP_USERS/user_id",
          "name": "user_id",
          "description": "Unique identifier of the user"
        },
        "guid": "2e5b4bdb-592d-4964-afbe-021214b0cc9f",
        "status": "ACTIVE",
        "displayText": "user_id",
        "classificationNames": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "createTime": 1655116523261,
        "updateTime": 1655460145909
      },
      {
        "typeName": "Table",
        "attributes": {
          "qualifiedName\"": "default/snowflake/1655116256/ATLAN_SAMPLE_DATA/FOOD_BEVERAGE/INSTACART_TOP_USERS",
          "name\"": "INSTACART_TOP_USERS",
          "description\"": "Top users across categories"
        },
        "guid": "c1ef6535-4c9d-4946-83a3-9f70d7a98e47",
        "status": "ACTIVE",
        "displayText": "INSTACART_TOP_USERS",
        "classificationNames": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
        "createTime": 1655116491284,
        "updateTime": 1655460145909
      }
    ],
    "guidAssignments": {
      "-786722728348341": "2992ae78-c480-48b9-b61a-67cce210e3d7",
      "-786722728348342": "f25aec9b-790f-4760-b66c-997eee2fe613"
    }
  }
}