Ataccama ONE Agentic Cloud Portal ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
User Community Service Desk Downloads

Documentation Flow 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 Documentation Flow API allows you to programmatically trigger documentation flows on your data source connections.

Documentation flows automate the process of discovering and enriching data assets in your catalog. A documentation flow runs asynchronously on a connection and can perform one or more of the following operations, depending on the configuration used: metadata import, term detection, profiling, and DQ evaluation.

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

API base URL

All Documentation Flow 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 documentation flow configurations

Retrieve a paginated list of available documentation flow configurations. Use this endpoint to find the configuration URN needed to start a documentation flow.

Request
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/documentation-flow/configurations?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 configurations to return.

Default: 20.

Max: 100.
Response example
{
  "meta": {
    "next": "2",
    "total": 3
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:documentation-flow-configuration:c53ebb75-b2f4-4ca5-bc73-0f2848b84374",
      "name": "Import metadata",
      "description": "Import metadata to the Data Catalog without accessing any data.",
      "configuration": "{\"actions\" : [\"IMPORT\"]}"
    },
    {
      "urn": "urn:ata:{your-tenant}:catalog:documentation-flow-configuration:a74ed274-ad79-4c87-bdcc-9a986363f763",
      "name": "Detect terms",
      "description": "Import metadata and detect terms based on detection rules.",
      "configuration": "{\"actions\" : [\"IMPORT\", \"TERM_DETECTION\"]}"
    }
  ]
}

The response includes the following fields for each configuration:

  • urn: URN identifier of the configuration.

  • name: Name of the documentation flow configuration.

  • description: Description of the documentation flow configuration.

  • configuration: Configuration of the documentation flow in JSON format.

Start a documentation flow

Start a documentation flow asynchronously with a given configuration on a connection. The request is accepted for processing and returns a workflow URN that identifies the running flow.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/documentation-flow/start" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationUrn": "urn:ata:{your-tenant}:catalog:documentation-flow-configuration:123e4567-e89b-12d3-a456-426614174000",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09"
  }'
Request body fields
Field Type Required Description

configurationUrn

string

Yes

URN of the documentation flow configuration to use. Retrieve available configurations using List documentation flow configurations.

connectionUrn

string

Yes

URN of the connection to run the documentation flow on. You can find connection URNs in catalog item responses using the Get a catalog item endpoint (connection.urn field).

paths

array of strings

No

List of paths to run the documentation flow on. When omitted, the flow runs on the whole connection.

The API returns the HTTP status code 202 Accepted, confirming that the flow has been accepted for asynchronous processing.

Response example
{
  "workflowUrn": "urn:ata:{your-tenant}:processing:workflow:a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

The response includes:

  • workflowUrn: URN of the processing workflow created for this documentation flow.

Complete example

Here’s a complete example that lists available configurations and starts a documentation flow:

# 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 available documentation flow configurations
curl -s -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/documentation-flow/configurations" \
  -H "Authorization: Bearer $TOKEN"

# 3. Start a documentation flow on a connection
curl -s -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/documentation-flow/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationUrn": "urn:ata:{your-tenant}:catalog:documentation-flow-configuration:123e4567-e89b-12d3-a456-426614174000",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09"
  }'

# 4. Start a documentation flow on specific paths only
curl -s -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/documentation-flow/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationUrn": "urn:ata:{your-tenant}:catalog:documentation-flow-configuration:123e4567-e89b-12d3-a456-426614174000",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09",
    "paths": ["public/customers", "public/orders"]
  }'

Error handling

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

Status code Description

200 OK

Configuration listing successful.

202 Accepted

Documentation flow accepted for asynchronous processing.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Configuration or connection does not exist.
Error response example
{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Resource 'urn:ata:acme-corp:catalog:documentation-flow-configuration:123e4567-e89b-12d3-a456-426614174000' was not found"
}

Next steps

Was this page useful?