Sources 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 Sources API allows you to programmatically manage sources in the Ataccama ONE catalog. Sources represent the systems your data assets originate from, such as databases or file storage, and group the related catalog items.

Use this API to recreate sources when importing metadata from external systems, for example, when migrating data source definitions from another platform.

Before using the Sources API, configure authentication as described in API Authentication.

API base URL

All Sources API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/catalog/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

List sources

Retrieve a paginated list of all sources.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/sources?size=20" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`size`	integer	No	Number of sources to return. Default: `20`. Max: `100`.
`sort`	string	No	Comma-separated field names for sorting results. Prefix a field with `-` to sort descending. Supported fields: `name`. Examples: `?sort=name` (ascending), `?sort=-name` (descending).
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isCritical,community,domains`. See Work with extra properties.

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 12
  },
  "data": [
    {
      "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"
      }
    }
  ]
}

Create a source

Create a source in the catalog. The server generates the URN for the created source automatically.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/sources" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales USA",
    "description": "Source system holding US sales records",
    "stewardship": {
      "groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  }'

Request body fields
Field	Type	Required	Description
`name`	string	Yes	Name of the source.
`description`	string	No	Description of the source.
`stewardship`	object	No	Stewardship assignment for the source. Contains `groupUrn`, the URN of the group responsible for stewardship.
`extraProperties`	object	No	Extra property values to set on the source, as a map of property names and values. See Work with extra properties.

The response returns the HTTP status code 201 Created with the created source, including its generated URN.

Get a source

Retrieve detailed information about a specific source by its URN.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/sources/{urn}" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`urn`	string	Yes	URN identifier of the source. For example: `urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f`.

Query parameters
Parameter	Type	Required	Description
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isCritical,community,domains`. See Work with extra properties.

Response example

{
  "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"
  }
}

Update a source

Update specific fields of a source using JSON Merge Patch (RFC 7386). You only need to specify the fields you want to change.

Request

curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/sources/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description of the source",
    "stewardship": {
      "groupUrn": "urn:ata:{your-tenant}:iam:group:123e4567-e89b-12d3-a456-426614174000"
    }
  }'

Request body fields
Field	Type	Required	Description
`name`	string	No	Updated name for the source.
`description`	string or null	No	Updated description for the source.
`stewardship`	object or null	No	Stewardship assignment for the source. Contains `groupUrn`, the URN of the group responsible for stewardship. Set to `null` to clear the stewardship.
`extraProperties`	object or null	No	Extra property values to update, as a map of property names and values. Only the properties listed in the body are modified. To clear a value, set a scalar property to `null` or a reference array property to `[]`. See Work with extra properties.

The response returns the updated source with all fields (same structure as Get a source).

Delete a source

Delete a source from the catalog.

Request

curl -X DELETE "https://{your-environment}.ataccama.one/api/catalog/v1/sources/{urn}" \
  -H "Authorization: Bearer {access_token}"

The response returns the HTTP status code 204 No Content on success.

Work with extra properties

Sources support custom properties defined in the metadata model of your environment. The API refers to these custom properties as extra properties.

Extra properties work the same way for sources as for catalog items:

To retrieve them, list the property names you need in the extraProperties query parameter of the List sources or Get a source endpoint. When omitted, no extra properties are returned.
To set or update them, use the extraProperties field in the Create a source or Update a source request body.

The property names must exactly match the property names defined in the metadata model. To find which properties are available, use the Metadata Model API to retrieve the source entity definition. For details about supported value types and update behavior, see Work with extra properties in the Catalog Items API documentation.

Complete example

Here’s a complete example using cURL to work with sources:

# 1. Obtain access token
TOKEN=$(curl -s -X POST "https://{your-environment}.ataccama.one/auth/realms/{your-realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your-client-id}" \
  -d "client_secret={your-client-secret}" \
  | jq -r '.access_token')

# 2. List all sources (sorted by name)
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/sources?size=20&sort=name" \
  -H "Authorization: Bearer $TOKEN"

# 3. Create a source
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/sources" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales USA",
    "description": "Source system holding US sales records"
  }'

# 4. Get a specific source
SOURCE_URN="urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/sources/$SOURCE_URN" \
  -H "Authorization: Bearer $TOKEN"

# 5. Update the source description
curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/sources/$SOURCE_URN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated source description"
  }'

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

Status code	Description
`200 OK`	Request successful.
`201 Created`	Source created successfully.
`204 No Content`	Delete successful.
`400 Bad Request`	Invalid request parameters or body.
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Source does not exist.

200 OK

Request successful.

201 Created

Source created successfully.

204 No Content

Delete successful.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Source does not exist.

Error response example

{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Source with ID '28e3ca71-635b-43c4-9d1b-bc9cc642721f' was not found"
}

Next steps

Learn about managing catalog items representing the data assets in your sources.
Learn about documentation flows to trigger metadata import, term detection, and data quality evaluation on your connections.
Use the Metadata Model API to discover the extra properties available for sources in your environment.
Download the Catalog API OpenAPI specification for detailed API reference.

Was this page useful?