List purposes

GET /api/service/purposes

List all the purposes defined in Atlan.

Query parameters

  • limit integer(int32)

    Maximum number of purposes to be returned.

  • offset integer(int32)

    Starting point for purposes to return, for paging.

  • sort string

    Property by which to sort the purposes.

    Values are createdAt, createdBy, updatedAt, or updatedBy.

  • count boolean

    Whether to return the total count of purposes or not. If set to false both totalRecord and filterRecord will return 0.

    Default value is true.

  • columns array[string]

    Specific columns to retrieve for each purpose. Value of unspecified columns will be returned as null or empty strings.

  • filter object

    Filter purposes to retrieve based on RQL

Responses

  • 200 object

    Successfully returned purposes present in Atlan.

    • totalRecord integer(int32) | null

      Total count of purposes returned.

    • filterRecord integer(int32) | null

      Total count of filtered purposes returned. Will have the same value as totalRecord if no filter is applied.

    • records array[object] | null

      Instance of a purpose in Atlan, with its detailed response-specific information.

      • id string | null

        Unique identifier of the purpose.

      • name string

        Unique system name for the purpose. This will generally be the same as the displayName, but must be unique.

      • displayName string | null

        Human-readable name of the purpose. This is what is shown on the UI, and while not strictly required for creation if it is missing then no name will be displayed for the purpose in the UI.

      • description string | null

        Meaningful explanation for what the purpose represents or how it is used.

      • metadataPolicies array[object] | null

        Instance of a metadata policy for a purpose in Atlan, with its detailed response-specific information.

        • actions array[string] | null

          List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose.

          Permissions are as follows:

          • entity-read: view activity, lineage, custom metadata and SQL queries for processes in lineage or view definitions
          • entity-update: update asset metadata including description, certification, owners, readme and resources
          • entity-create: create new assets within the selected connection or specified database/schema (via API)
          • entity-delete: delete assets within the selected connection or specified database/schema (via API)
          • entity-update-business-metadata: update custom metadata values for the assets
          • entity-add-classification: attach classifications to assets
          • entity-remove-classification: remove classifications from assets

          Values are entity-read, entity-update, entity-create, entity-delete, entity-update-business-metadata, entity-add-classification, or entity-remove-classification.

        • allow boolean | null

          If false, this applies an "explicit deny" to the listed permissions. Those permissions will not be granted to any users on the policy, even if those users are parts of other policies that do give them those permissions. In other words, this "explicit deny" will take precedence over all other permissions for the same classifications and users.

        • name string | null

          Meaningful explanation of the policy.

        • description string | null

          Unused.

        • users array[string] | null

          List of unique usernames to whom the policy will apply.

        • groups array[string] | null

          List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.

        • allUsers boolean | null

          When true, the policy will apply to all users in Atlan (present and future).

        • type string

          Type of policy. For metadata policies, this should always be metadata.

        • createdAt integer(int64) | null

          Date and time (epoch) at which the policy was created, in milliseconds.

        • createdBy string | null

          User who created the policy.

        • updatedAt integer(int64) | null

          Date and time (epoch) at which the policy was last updated, in milliseconds.

        • updatedBy string | null

          User who last updated the policy.

        • id string | null

          Unique identifier (GUID) for the policy.

      • dataPolicies array[object] | null

        Instance of a data policy for a purpose in Atlan, with its detailed response-specific information.

        • actions array[string] | null

          List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose. For data policies the only possible permission is select, which applies to both previewing and querying data.

          Value is select.

        • allow boolean | null

          If false, this applies an "explicit deny" to preview and query permission. This denial for previewing and querying applies to entire tables. So even if only a single column has a classification linked to this purpose, in the case of an "explicit deny" users in this policy will be unable to preview or query the entire table in which that column exists.

        • name string | null

          Meaningful explanation of the policy.

        • description string | null

          Unused.

        • users array[string] | null

          List of unique usernames to whom the policy will apply.

        • groups array[string] | null

          List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.

        • allUsers boolean | null

          When true, the policy will apply to all users in Atlan (present and future).

        • type string | null

          Type of policy. To grant or deny access to data entirely (without masking), use access. To only mask the classified assets, use masking.

          Values are masking, access, or null.

        • mask string | null

          Type of masking to apply when the type property is set to masking.

          Values are heka:MASK_SHOW_FIRST_4, heka:MASK_SHOW_LAST_4, heka:MASK_HASH, heka:MASK_NULL, heka:MASK_REDACT, or null.

        • createdAt integer(int64) | null

          Date and time (epoch) at which the policy was created, in milliseconds.

        • createdBy string | null

          User who created the policy.

        • updatedAt integer(int64) | null

          Date and time (epoch) at which the policy was last updated, in milliseconds.

        • updatedBy string | null

          User who last updated the policy.

        • id string | null

          Unique identifier (GUID) for the policy.

      • tags array[string] | null

        List of classifications that this purpose operates against.

        Each name is the internal, uniquely hashed classification name and not the human-readable name of a classification.

      • readme string | null

        URL-encoded HTML representing the richly-formatted readme for the purpose.

      • createdAt integer(int64) | null

        Date and time (epoch) at which the purpose was created, in milliseconds.

      • createdBy string | null

        User who created the purpose.

      • updatedAt integer(int64) | null

        Date and time (epoch) at which the purpose was last updated, in milliseconds.

      • updatedBy string | null

        User who last updated the purpose.

      • level string | null

        Level of the created purpose. (This will always be workspace.)

      • version string | null

        Unique identity for the version of the purpose.

      • enabled boolean | null

        True when this purpose is turned on, and false when it is turned off.

      • resources string | null
      • attributes object | null
      • isActive boolean | null

        True when the purpose is currently enabled, false otherwise.

GET /api/service/purposes
curl \
 -X GET https://tenant.atlan.com/api/service/purposes \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "totalRecord": 1,
  "filterRecord": 1,
  "records": [
    {
      "id": "3f35d508-4f43-48d3-84e3-889c13571f1c",
      "version": "small-sun-5855",
      "isActive": true,
      "createdAt": 1655214527401,
      "updatedAt": 1655214527401,
      "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
      "description": null,
      "displayName": null,
      "name": "PII Protection",
      "dataPolicies": [],
      "metadataPolicies": [],
      "tags": [
        "rXlsT2vyr7mYtH1aCNLU6F"
      ],
      "level": "workspace",
      "enabled": true,
      "readme": null,
      "resources": null,
      "attributes": null
    }
  ]
}