The signature is a JSON-based parameter supported by the Aggregated Context API that you can use to tailor the API response to your specific use case. It allows you to precisely define:

• Which object types the API should search (for example: tables, columns, or documentation objects)
• Which fields should be included in the results
• What filters should be applied to define the catalog objects that are in scope
• What fields to include for child columns in tables

In this guide:

• Why Use a Signature?
• Context API Modes and the Signature
• Signature Structure
• Supported Object Fields
• Search Filters
• Child Objects
• Limit
• Full Signature Template
• Signature Examples
• Construct an Effective Signature Step by Step

Why Use a Signature?

Without a signature, the API searches across the entire catalog and can return matches from any supported object type, including content that may not be relevant, such as uncertified or organization-wide assets.

Using a signature allows you to narrow the scope to specific object types, departments, or trusted assets, such as certified or gold standard tables, which helps improve the precision and relevance of the results.

A well-crafted signature can enable:

• Domain-specific results (for example: Only the information in the HR domain)
• Performance optimization of the API request
• Granular control over the context down to the field level
• Support for downstream LLM integrations by reducing response size

Context API Modes and the Signature

The Context API operates in two modes: search (default) and bulk that are specified as API request parameters. The mode parameter defines the mode. If omitted, the search mode is applied by default.

Understanding these modes is important for working with signatures, as they influence how the signature object is used:

• search (default): This is a conversational mode where you provide a natural language question. Using a signature in search mode is recommended, but optional. If you don’t provide a signature, the API defaults to its broadest scope, including all supported object types. In this case, default required fields are used to fetch the context, and all other available fields may be included as optional.
• bulk: This mode is for direct object retrieval in bulk operations. The signature object is mandatory in bulk mode and precisely defines the objects to be retrieved. The Documentation object type is not supported in bulk mode, and the optional fields aren’t used.

Signature Structure

The top-level keys of a signature JSON object are object types. You can include any combination of the following top-level keys:

• schema
• table
• column
• documentation(available only in search mode)
• query
• bi_folder
• bi_report
• bi_field

Each object type further accepts the following configuration options:

The table, query, and bi_report object types additionally support the child_objects object:

Supported Object Fields

Each object type supports its own specific fields, detailed below. These fields can be listed in the fields_required, fields_optional, and child_objects keys of the signature.

Schema Fields

Default required fields: name, title, description,url

Table Fields

Default required fields: name, title, description, url

Column Fields

Default required fields: name, title, data_type, url

Documentation Object Fields

Default required fields: title, content, url, custom_fields

Query Fields

Default required fields: title, description, content, url

BI Folder Fields

In Context API requests, use bi_folder to represent the BI folder object.

Default required fields: name, description, bi_object_type, url

BI Report Fields

In Context API requests, use bi_report to represent the BI report object.

Default required fields: name, description, bi_object_type, url, bi_fields

BI Field Fields

In Context API requests, use bi_field to represent the BI report object.

Default required fields: name, description, bi_object_type, data_type, role, expression

Retrieving Custom Fields

For richer context, the API can return custom fields for the schema, table, column, documentation, and BI objects.

Query objects currently don’t support the retrieval of custom fields.

For documentation objects, custom fields will not be returned for the legacy article object type. article is a deprecated object type that should be replaced by documents.

custom_fields can only be requested within the top-level fields_required key of the signature; it is not supported in fields_optional or as a child_object field.

{
  "table": {
     "fields_required": ["title", "name", "custom_fields"]
     }
}

By default, all custom fields and their values associated with an object will be returned if you include custom_fields into fields_required. To retrieve a specific subset of custom fields, you can further provide a list of their IDs or names using the custom_fields key on the same level with fields_required.

{
  "table": {
     "fields_required": ["title", "name", "custom_fields"],
     "custom_fields": [8, "Certification Date", 10013]
     }
}

📘

Using custom field IDs is recommended for signature stability.

Alation allows custom fields of different types to share the same name, though this is not recommended. API requests for custom fields with duplicate names will fail with a 400 error.

Custom field names can be changed by an administrator, which may invalidate a signature in your implementation. If a custom field name specified in a signature cannot be resolved, the Context API call will also fail with a 400 error.

Using the object_id and object_type Fields

The object_id and object_type fields can be included in the signature for all object types (schemas, tables, columns, documentation, queries, BI objects) to support integration with other Alation APIs and the AI Agent SDK tools. These fields are returned only when explicitly requested via the fields_required key.

Search Filters

Use search_filters to narrow the scope of returned objects. Supported filters can include these keys:

domain_ids

Filter by IDs for domains:

{
    "search_filters":{
       "domain_ids": [ID_1, ID_2]
       }
}

• domain_ids = the key to use for domains
• [ID_1, ID_2] = list of specific domain IDs you're filtering with

fields

Filter on custom field values:

{
    "search_filters":{
       "fields": {
          "cf[ID]":["value_1", "value_2"]
        }
     }
}

• cf[ID] = the system ID of the custom field
• ["value_1", "value_2"] = the field values you're filtering on

tag_ids

Filter by tags. Tags are referenced inside the fields key:

{
   "search_filters":{
      "fields": {
         "tag_ids": [ID_1, ID_2]
      }
    }
}

• tag_ids = the key to use for the tags filter
• [ID_1, ID_2] = list of specific tag IDs you’re filtering on

flags

Filter by trust flags:

{
    "search_filters": {
       "flags":["Endorsement","Deprecation","Warning"]
       }
}

• flags = the key to use for the flags filter
• ["Endorsement","Deprecation","Warning"] = list of the flag values you're filtering on

Example Signature

Let's assume you'd like to construct a signature like the following:

Limit the context to the table object type within the HR domain (has the ID of 10), with the custom field of Picker type Confidentiality (has the ID of 10559) set to Public or Internal (other confidentiality values of Restricted and Confidential are not included), with the Gold tag (has the ID of 1), and the Endorsed flag:

{
  "table": {
     "search_filters": {
        "domain_ids": [10],
        "fields": {
           "tag_ids": [1],
           "cf[10559]": ["Public", "Internal"]
         },
        "flags": ["Endorsement"]
     }
  }
}

Child Objects

Use the child_objects key to customize which fields are returned for nested (child) objects.

As of version 2025.1.5, we support the child_objects key for the table, query, and bi_report object types.

📘

Maximum Child Objects Returned

A maximum of 50 child objects are returned per table and query parent object, and a maximum of 100 per BI report. Child objects with popularity data are ranked first. The rest are added afterward in the order they were retrieved or are selected randomly.

You may have noticed that object types can function in two ways within a signature: as higher-level object type keys and as lower-level specifiers for nested objects:

• Object types keys: When an object type (schema, table, etc.) is used as the object type key in the signature, it limits the overall scope of the request to objects of that type. It acts as the main container, and any other filters included within its definition apply only to matching objects.

• Object types as child objects keys: When an object type is specified for the child_objects key, it specifies which related child objects and their fields should be included. This allows you to further refine the data retrieved for these specific child objects by specifying which of their fields you need.

Supported Child Objects

Table Object Type

columns

To customize the response for columns within tables, use the columns key inside the child_objects key for the table object type.

Include this key only if you’ve also included columns in either the fields_required or fields_optional keys of your query signature for the table object.

The columns key within child_objects allows you to define exactly which column fields to return for each column within the returned tables.

In summary:

• If columns is included in either fields_required or fields_optional and in child_objects, you will receive the columns for each table, with the fields specified in the nested structure.
• If columns is included only in fields_required or fields_optional, but not in child_objects, the response will include columns with the default set of column fields.
• If columns is included only in child_objects, but not in fields_required or fields_optional, the response will not include columns, as they were not explicitly requested in any of the fields_ keys. This is not a valid format.

Use the following format:

{ 
"table": {
 
    // List of fields that must be included in the response for tables:
    
    "fields_required": ["name", "title", "description", "url", "columns"],
       
    // Only use context from these specific fields for the child columns: 

    "child_objects": {
        "columns": {
           "fields": ["name", "data_type", "description"]
            }
         }
  }
}

This structure translates to:

Retrieve information primarily about table objects. For each table retrieved, also include information about its child column objects, but only return the name, data_type, and description fields for those columns.

common_queries

To customize the list of the query fields to return for each common query associated with a table, use the common_queries key within the child_objects section of the table object.

This key should only be used if common_queries is also listed in either the fields_required or fields_optional sections of your signature for the table object.

📘

Note

The child_objects key is not supported within common_queries. Only the fields key is allowed.

In summary:

• If common_queries is included in either fields_required or fields_optional and in child_objects, you will receive the associated common queries for each table, with the fields specified in the nested structure.
• If common_queries is included only in fields_required or fields_optional, but not in child_objects, the response will include common queries with a default set of fields.
• If common_queries is included only in child_objects, but not in fields_required or fields_optional, common queries will not be returned, as they were not explicitly requested in any of the fields_ keys. This is not a valid format.

Use the following format:

{
"table": {
 
    // List of fields that must be included in the response for tables:
    
    "fields_required": ["name", "title", "description", "url", "columns", "common_queries"],
       
    // For each table, also use context from common queries and these fields of the queries: 

    "child_objects": {
         "common_queries": {
             "fields": ['title', 'description', 'content', 'url']
              }
          }
  }
}

This structure translates to:

Retrieve information primarily about table objects. For each table retrieved, also include information about its common queries, returning the title, description, content, and the URL fields for those queries.

Query object type

mentioned_tables

To further specify the table fields returned in the response for the mentioned tables, use the mentioned_tables key within the child_objects key of the query object.

Include this key only if you’ve also specified mentioned_tables in either the fields_required or fields_optional keys of your signature for the query object.

For even more detailed control, you can nest another child_objects key under mentioned_tables and specify columns as a child object. The structure of the mentioned_tables object mirrors that of the table object, allowing you to define which fields to include for columns within the mentioned tables.

📘

Note

The common_queries key is not supported under mentioned_tables and cannot be used at this level of nesting.

In summary:

• If mentioned_tables is included in either fields_required or fields_optional and in child_objects, you will receive the mentioned tables in the response, with the specified fields as defined in the nested structure.
• If mentioned_tables is included only in fields_required or fields_optional, but not in child_objects, the response will include the mentioned tables with the default set of table fields.
• If mentioned_tables is included only in child_objects, but not in fields_required or fields_optional, the response will not include the mentioned tables, as they were not explicitly requested in any of the fields_ keys. This is considered an invalid query format.

Use the following format:

{
"query": {
    "fields_required": ["title", "description", "content", "mentioned_tables"],
    "child_objects": {
         "mentioned_tables": {
             "fields": ["name", "title", "columns"],
             "child_objects": {
                "columns": {
                     "fields": ["name", "data_type", "sample_values"]
                      }
                  }
              }
     }
  }
}

This structure translates to:

Retrieve information about query objects. For each query retrieved, return the required fields, also including information about the tables mentioned in the query, returning the name, title, and child columns. For the child columns of the mentioned queries, return the field name, data type, and sample values.

BI report object type

To request BI fields in the response, add the bi_fields key under bi_report in either the fields_required or fields_optional section. Then, include bi_fields again under child_objects within bi_report to further specify which fields to return for the relevant BI fields.

In summary:

• If bi_fields is included in either fields_required or fields_optional and in child_objects, you will receive the specified fields in the response.
• If bi_fields is included only in fields_required or fields_optional, but not in child_objects, the response will include all bi_fields with the default set of BI field fields.
• If bi_fields is included only in child_objects, but not in fields_required or fields_optional, the response will not include the bi_fields, as they were not explicitly requested in the fields_ section. This is considered an invalid query format.

Use the following format:

{
  "bi_report": {
     "fields_required": [
       "name",
       "description",
       "bi_object_type",
       "bi_fields",
       "url",
       "source_comment",
       "custom_fields",
       "object_id",
       "object_type"
     ],
     "child_objects": {
       "bi_fields": {
          "fields": [
            "name",
            "data_type",
            "expression",
            "role",
            "description"
           ]
         }
       }
     }
}

This structure translates to: Retrieve information about BI report objects. For each BI report retrieved, return the required fields, also including information about the BI fields included into the BI report and return the name, data type, description, role, and expression for the BI fields.

Limit

The limit key specifies the maximum number of objects to retrieve. If this key is not provided, the API applies the following default limits:

• Search mode: 2 objects per type
• Bulk mode: 50 objects per type
• Maximum: 1,000 objects per type

{
  "table": {
    "search_filters": {
       "domain_ids": [1]
       },
    "limit": 50
    },
  "column": {
     "search_filters": {
        "domain_ids": [1]
      },
     "limit": 100
     }
}

This structure translates to: Only return 50 table and 100 column objects from a given domain.

Full Signature Template

Here's a full template you can use for constructing your own signature objects:

{
    "schema": {
      "fields_required": ["name", "title", "description", "url", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": [],
      "search_filters": {},
      "limit": 100         
    },
    "table": {
      "fields_required": ["name", "title", "description", "url", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": ["common_joins", "common_filters", "columns"],
      "child_objects": {},
      "search_filters": {},
      "limit": 100
    },
    "column": {
      "fields_required": ["name", "title", "data_type", "url", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": ["sample_values"],
      "search_filters": {},
      "limit": 100
    },
    "documentation": {
      "fields_required": ["title", "content", "url", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": [],
      "search_filters": {},
      "limit": 100
    },
    "query": {
       "fields_required": ["title", "description", "content", "url", "object_id", "object_type"],
       "fields_optional": [],
       "child_objects": {},
       "search_filters": {},
       "limit": 100
    },
    "bi_folder": {
      "fields_required": ["name", "description", "bi_object_type","url", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": [],      
      "search_filters": {},
      "limit": 100
      },
    "bi_report": {
        "fields_required": ["name", "description", "bi_object_type","url", "custom_fields", "bi_fields", "object_id", "object_type"],
        "child_objects": {
          "bi_fields": {
             "fields": ["name", "data_type", "expression", "role", "description"]
           }
         },
      "custom_fields": [],
      "fields_optional": [],
      "search_filters": {},
      "limit": 100
      },
    "bi_field": {
      "fields_required": ["name", "description", "data_type", "role", "expression", "bi_object_type", "custom_fields", "object_id", "object_type"],
      "custom_fields": [],
      "fields_optional": [],  
      "search_filters": {},      
      "limit": 100
     }
}

Signature Examples

Tables Only

{
  "table": {
    "fields_required": ["name", "title", "description", "url"]
  }
}

This signature:

• Returns only table objects.
• Includes name, title, description, and url in every response as they're required fields.
• The fields_optional field isn't included, so every response will only include the required fields.
• Searches the entire catalog, as no search filters are included.

Tables with Dynamic Field Selection

{
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "common_filters"]
  }
}

This signature:

• Returns only table objects.
• Includes name, title, description, and url in every response as they're required fields.
• Intelligently includes common_joins and/or common_filters only when relevant to the user's question (for example, if a user asks What tables can be joined with the sales table?, the response will include the common_joins data).
• Searches the entire catalog, as no search filters are included.

Data Analyst Agent

{
  "table": {
    "fields_required": ["name", "title", "description", "url", "common_joins", "common_filters", "columns"],
    "search_filters": {
        "flags": ["Endorsement"],
        "fields": {
            "tag_ids": [123],
            "cf[10568]":["Certified"] 
          }
    },
    "child_objects": {
    "columns": {
        "fields": ["name", "data_type", "description", "sample_values"]
      }
    }
  },
  "query": {
    "fields_required": ["title", "description", "content", "url"],
    "search_filters": {
       "fields": {
         "tag_ids": [123]
       }
    }
  },
  "documentation": {
    "fields_required": ["title", "content", "url"],
    "search_filters": {
      "fields": {
        "tag_ids": [123] 
      }
    }
  }
}

This signature is optimized for analytical work by focusing on high-quality assets (endorsed and tagged) with complete metadata:

• Returns table, query, and documentation objects relevant to the question.

• For tables:

  • Includes comprehensive information like common_joins, common_filters and columns details.
  • Filters for only trusted (endorsed) tables with the specific tag ID =123 and the value Certified in the custom field with ID =10568.
  • For each table, includes detailed column information with sample_values.

• For queries and documentation objects:

  • Includes the complete content to provide analysis context.
  • Filters to only include objects with tag ID =123.

Question and Answer Agent

{
  "schema": {
    "fields_required": ["name", "title", "description", "url"],
    "search_filters": {
      "domain_ids": [123]
    }
  },
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "common_filters", "columns"],
    "search_filters": {
      "domain_ids": [123]
    },
    "child_objects": {
      "columns": {
        "fields": ["name", "data_type", "description", "sample_values"]
      }
    }
  },
  "column": {
    "fields_required": ["name", "title", "data_type", "url"],
    "fields_optional": ["description", "sample_values"]
  },
  "documentation": {
    "fields_required": ["title", "content", "url"],
     "search_filters": {
      "domain_ids": [123]
    }
  },
  "query": {
    "fields_required": ["title", "description", "content", "url"],
    "search_filters": {
      "domain_ids": [123]
    }
  }
}

This signature:

• Is designed for building a Question & Answer system focused on a specific business domain (domain ID =123), ensuring all responses remain relevant to that particular subject area.
• Supports comprehensive questions and answers by including all major object types (schema, table, column, documentation, and query). It's important to note that the Alation API will return only the relevant object types for each question, not all types in every response. This means that the search will look across schemas, tables, columns, documentation, and queries, but for any given question, it will only return the types that are relevant to that specific context.
• Uses optional fields for tables and columns to provide dynamic responses based on the context of the question.

Analysis Using BI Objects

{
  "bi_folder": {
    "fields_required": ["name", "description", "bi_object_type", "url"],
    "fields_optional": ["source_comment"],
    "limit": 5
  },
  "bi_report": {
    "fields_required": ["name", "description", "url", "bi_object_type", "bi_fields"],
    "fields_optional": ["source_comment"],
    "child_objects": {
      "bi_fields": {
        "fields": ["name", "data_type", "role", "description", "expression"]
      }
    },
    "limit": 15
  },
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["columns"],
    "child_objects": {
      "columns": {
        "fields": ["name", "title", "data_type", "description"]
        }
     },
    "limit": 15
  }
}

This signature:

• Returns context for dashboards, key metrics, and supporting data tables relevant to the question.
• Uses optional fields for BI folders, BI reports, and tables to provide dynamic responses based on the context of the question.
• Limits the number of objects to consider per object type using the limit key.

Construct an Effective Signature Step by Step

• Step 1: Identify the Object Types you Need
• Step 2: Define Required and Optional Fields for Each Object
• Step 3: Add Search Filters (Optional)
• Step 4: Add Child Objects (Optional)
• Step 5: Add Limit
• Step 6: Combine into a Signature Object
• Step 7: Validate and Test
• Step 8: Iterate to Optimize

Step 1: Identify the Object Types you Need

Start by deciding which types of supported catalog objects your application or agent needs to process.

Step 2: Define Required and Optional Fields for Each Object

Each object type in the Aggregated Context API supports a defined set of fields. For each object type:

• Use fields_required to specify fields that must always be included in the response (for example, name and description). This provides a predictable and repeatable structure of the response, which can be important in AI application development where consistent output is the goal. Include custom_fields into fields_required for richer context.

• Use fields_optional for fields that are helpful but not essential (for example, sample_values, common_joins). These fields can enrich responses, but since their availability varies, they may appear inconsistently or more frequently than expected. fields_optional should only be used in the search mode.

If both fields_required and fields_optional are left empty, the API falls back to default fields. This is acceptable in exploratory or low-stakes scenarios, but including at least fields_required is strongly recommended for more controlled and stable behavior.

📘

Best practice

Use fields_required for the core fields your application depends on. Add only a small number of carefully selected fields to fields_optional if you need additional context.

Example:

{
"table":{
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "columns"]
}
}

Step 3: Add Search Filters (Optional)

Use search_filters to scope your context query to specific slices of the catalog.

You can filter by:

• Domains: For example, restrict the context to catalog metadata from a particular domain only
• Custom fields: For example, filter on a specific custom field with specific values only
• Tags: For example, restrict the context to objects with a specific tag only
• Flags: For example, restrict to “Endorsed” objects only

Constructing search filters within the signature requires that you know the system IDs of the entities that you include into the search filters.

You can find out the domain IDs, custom field IDs, and tag IDs from your Alation catalog user interface. Flag values are fixed system values.

• Find out the Domain ID
• Find out the Custom Field ID
• Find out the Tag ID
• Flag Values to Use
• Example of a Search Filter

Find out the Domain ID

1. Log in to Alation.

2. Use the left-side navigation to select the domain you need. The catalog page of the domain will open. (Do not use the drop-down at the top of the page where you can select My domains Only.)

3. Look at the URL. It includes the domain ID. For example, in the URL https://my_catalog.com/app/domain/36/overview, 36 is the domain ID.

4. Make a note of this ID value, along with the domain name. For example:

   Domain name: Alation Discovery Series
   ID = 36

5 Repeat the search for each domain you want to include in the signature.

📘

Alternatively:

You can use the Get Domains API to retrieve a list of all domains and their IDs. This endpoint is accessible to users with the Catalog Admin and Server Admin roles.

Find out the Custom Field ID

1. Log in to Alation.

2. Click into the Search bar and hit return. The full-page Search page will open.

3. Under Filters in the left-side filter panel, locate or add the custom field you need.

4. Select a field value. For example, in the screenshot below, the Bank Details value of the Categories of Personal Data custom field is selected.

   

5. After you select a value, the Search results page will update, only displaying matching objects.

6. Look at the URL field. The field ID will be included in the encoded URL. For example, in the URL like: https://my_catalog.com/app/full_search?limit=25&row_num=0&results_view=list&filters=%7B%22fields%22%3A%7B%22cf%5B10578%5D%22%3A%5B%22Bank+Details%22%5D%7D%7D, the encoded custom field ID is %22cf%5B10578%5D%22%3A%5B%22.

7. Use URL decoder software of your choice to retrieve the field ID. In the example above, it's 10578.

8. Make a note of the ID value, along with the field name. For example:

   Custom field: Categories of Personal Data
   ID = 10578
   Available values: Bank Details, Contact Details, Employment History

9. Repeat the search for each custom field you want to include in the signature.

📘

Alternatively:

If you are a Server or Catalog Admin, you can use the GET endpoint of the Custom Fields API to see which fields are available and what the field IDs are: <base_instance_URL>/integration/v2/custom_field/?values=id,name_singular&limit=1000.

Find out the Tag ID

1. Log in to Alation.

2. In the Search bar, type the keyword for the tag you're interested in and hit return. The Search results page will open.

3. Under Filters in the left-side filter panel, expand the Object Types filter.

4. Select the Tag object type. The Search results page will update to only display tag objects.

   

5. Click the tag you want the ID for. The catalog page of this object will open.

6. Look at the URL. The number after /tag/ is the tag ID. For example, in the URL https://my_catalog.com/app/tag/1/overview, 1 is the ID of this tag.

7. Make a note of this ID, with the tag name for reference. For example:

   Tag: healthcare
   ID = 1

8. Repeat the search for other tags you need.

📘

Alternatively:

In your Alation catalog, locate a catalog object that has the desired tag applied. Click the tag name to open its detail page. The URL will include the tag's unique ID.

Flag Values to Use

To create a search filter by flags, use these values:

• "Endorsement" for the endorsement flag
• "Deprecation" for the deprecation flag
• "Warning" for the warning flag in the Classic User Experience or the Important Info flag in the New User Experience.

The values are case-sensitive and should be used as shown below. You can include one or multiple values in the filter:

One flag:

{
   "search_filters":{
     "flags":["Endorsement"]
     }
}

Multiple flags:

{
   "search_filters":{
     "flags":["Endorsement","Deprecation","Warning"]
     }
}

📘

Alternatively:

Listing all three flag types ("Endorsement","Deprecation","Warning") will not return all objects. It will only return objects that have one or more of these flags applied. Any object without a flag will be excluded from the results.

Example of a Search Filter

The example below shows multiple keys and values used in the search_filters key. (This example is intended as an illustration to demonstrate format and structure. It's not meant to reflect a typical or recommended use case. In practice, most configurations will use a smaller, more focused set of options.)

{
   "search_filters":{
      "domain_ids":[10, 11, 12],        
      "fields": {
        "tag_ids":[1, 10, 20],
        "cf[10559]":["Candidate", "Done"],
        "cf[10558]":["In review", "Approved"],
        "cf[10557]":["Yes"]
        },
      "flags":["Endorsement","Warning"]
    }
}

Step 4: Add Child Objects (Optional)

If the responses can potentially include a lot of nested (child) objects, you can specify which fields to return for those child objects using child_objects. Use the child_objects key to potentially reduce token usage and improve response precision.

{
  "table": {
    "fields_required": ["name", "columns"],
    "child_objects": {
    "columns": {
      "fields": ["name", "data_type", "sample_values"]
    }
    }
  }
}

Step 5: Add Limit

If necessary, add the limit key to the objects you included. See Limit.

Step 6: Combine into a Signature Object

Structure your final signature as a top-level JSON object with each configured object type as a key.

Example:

{
  "schema": {
    "fields_required": ["name", "title", "description", "url"]
  },
  "table": {
    "fields_required": ["name", "title", "description", "url", "custom_fields"],
    "custom_fields": [80, 10034, 10078],
    "fields_optional": ["common_joins", "columns"],
    "search_filters":{
      "fields":{
        "tag_ids": [1]
        }
      },
    "child_objects": {
      "columns": {
        "fields": ["name", "data_type"]
      }
    },
    "limit": 50
  },
  "column": {
    "fields_required": ["name", "title", "data_type", "url"]
  }
}

Step 7: Validate and Test

Before deploying, validate your signature by:

• Checking if all required fields are present
• Running a test call against the Aggregated Context API
• Reviewing if filtering behaves as expected
• Monitoring response size and performance

Step 8: Iterate to Optimize

Once you've finalized your signature:

• Save reusable templates for different use cases
• Tune filters as your catalog grows
• Revisit fields periodically as new metadata types or fields are added to Alation