Stewardship API
|
The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable. We recommend testing thoroughly and being prepared to adapt to potential changes in future releases. |
The Stewardship API allows you to programmatically read and change which group is responsible for your data assets. Stewardship is a configurable trait, so the API works with any entity type that carries it: catalog items, terms, sources, and custom entity types alike. To learn how stewardship and stewardship inheritance work in Ataccama ONE, see Stewardship.
Use this API to transfer asset ownership between teams, for example, during a reorganization, or to assign stewardship in bulk after importing metadata from external systems.
Stewardship is managed only through the endpoints described on this page. The create and update endpoints of the Catalog Items API, the Terms API, and the Sources API don’t accept stewardship fields.
Before using the Stewardship API, configure authentication as described in API Authentication.
API base URL
All Stewardship API endpoints are accessed through the following base URL:
https://{your-environment}.ataccama.one/api/catalog/v1Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.
Retrieve effective stewardship
Effective stewardship is the stewardship that applies to an entity: either assigned directly to the entity or inherited from an ancestor, such as the source of a catalog item.
Effective stewardship is not returned by default.
To retrieve it, add include=effectiveStewardship to the list and get endpoints of the Catalog Items API (including the filter endpoint), the Terms API, the Sources API, and the Generic Metadata Entities API:
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/sources/{urn}?include=effectiveStewardship" \
-H "Authorization: Bearer {access_token}"The response then contains the effectiveStewardship field:
{
"urn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f",
"name": "Sales USA",
"description": "Source system holding US sales records",
"effectiveStewardship": {
"groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7",
"originUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
}
}The field contains:
-
groupUrn: URN of the group that acts as the steward of the entity. -
originUrn: URN of the entity the stewardship originates from. This is the entity itself when the stewardship is assigned directly to it, or the nearest ancestor that assigns one when the stewardship is inherited.
When the entity has no steward, assigned or inherited, the field is null.
Resolving effective stewardship takes additional processing time, so request it only when you need it.
Manage stewardship of an entity
Assign, transfer, or clear the stewardship of a single entity.
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/stewardship/manage" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"entityUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
"groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7",
"previousStewardAccessLevel": "viewMetadata"
}'| Field | Type | Required | Description |
|---|---|---|---|
|
string |
Yes |
URN of the entity whose stewardship is changed. Any entity type carrying the stewardship trait is accepted. |
|
string or null |
No |
URN of the group that becomes the steward of the entity. Set to |
|
string |
No |
Access level at which the entity is shared with the previous stewardship group so that it doesn’t lose access, for example, When omitted, the previous stewardship group loses access. |
Managing stewardship performs sharing, the same way as transferring stewardship in the web application:
-
The entity is shared with the new stewardship group.
-
The previous stewardship group keeps access only at the access level given in
previousStewardAccessLevel. -
Stewardship overrides are removed where needed.
The change is always published: it cannot be applied to a draft.
The response returns the stewardship of the entity after the change was applied:
{
"entityUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
"effectiveStewardship": {
"groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7",
"originUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54"
}
}When the assigned stewardship was cleared, effectiveStewardship contains the stewardship inherited from an ancestor, or null when no ancestor assigns one.
A request without groupUrn applies no change and simply returns the entity’s current effective stewardship.
Manage stewardship in batch
Change the stewardship of up to 100 entities in one call. Each item carries its own entity, group, and access level, so a single request can transfer different entities to different groups.
Each item accepts the same fields and behaves the same way as a single-entity request: the entity is shared with the new stewardship group, the previous stewardship group keeps access only at the given access level, and the change is published immediately.
Each item can also include an optional id.
The response returns the same id in the corresponding result so that you can match results to request items.
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/stewardship/batch/manage" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"data": [
{
"id": "item-1",
"entityUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
"groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7",
"previousStewardAccessLevel": "viewMetadata"
},
{
"id": "item-2",
"entityUrn": "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba",
"groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
]
}'| Constraint | Description |
|---|---|
Min items |
One entity required. |
Max items |
100 entities per request. |
Each item is processed independently: a failure on one item, for example, because the entity doesn’t exist or you don’t have access to it, doesn’t affect the other items.
The response returns the HTTP status code 207 Multi-Status with a meta summary (total, success, fail) and a results array in the same order as the request items.
Each result reports its own status: OK when the stewardship change was applied.
Any other value indicates failure and is accompanied by an error whose type matches the status, for example, RESOURCE_NOT_FOUND, STEWARDSHIP_NOT_SUPPORTED, or INVALID_ACCESS_LEVEL.
{
"meta": {
"total": 2,
"success": 1,
"fail": 1
},
"results": [
{
"id": "item-1",
"status": "OK"
},
{
"id": "item-2",
"status": "RESOURCE_NOT_FOUND",
"error": {
"type": "RESOURCE_NOT_FOUND",
"title": "Resource Not Found",
"detail": "Entity with URN 'urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba' was not found"
}
}
]
}Unlike the single-entity endpoint, the batch results don’t return the resulting effective stewardship.
To verify the outcome, retrieve the entities with include=effectiveStewardship (see Retrieve effective stewardship).
Error handling
The API returns standard HTTP status codes and problem details for errors:
| Status code | Description |
|---|---|
|
Stewardship change applied. |
|
Batch request processed.
Inspect |
|
Invalid request parameters or body. |
|
Insufficient permissions to access the requested resource. |
|
Entity does not exist. |
{
"type": "RESOURCE_NOT_FOUND",
"title": "Resource Not Found",
"detail": "Entity with URN 'urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54' was not found"
}Next steps
-
Learn how stewardship works in Ataccama ONE and how to assign it in the web application.
-
Learn about managing catalog items, terms, and sources through the API.
-
Use the Generic Metadata Entities API to work with custom entity types, including those with stewardship configured in the metadata model.
-
Download the Catalog API OpenAPI specification for detailed API reference.
Was this page useful?