Skip to main content

​
Getting Started

Get up and running with the Collate API and SDKs. This guide walks you through authentication, SDK installation, and making your first API call.

​
Prerequisites

  • A Collate account (cloud or self-hosted instance)
  • Your instance base URL (e.g., https://your-company.getcollate.io/api)
  • Python 3.11+, Java 21+, or Go 1.19+ (depending on your SDK choice)
1

Get Your API Credentials

You need a JWT token to authenticate API requests. There are two ways to get one:Bot Token (recommended for automation)
  1. Navigate to Settings > Bots in the Collate UI
  2. Click on the ingestion-bot (or create a new bot for your use case)
  3. Copy the JWT token from the bot details page
Navigate to Settings > Bots to find available botsCopy the JWT token from the bot details pagePersonal Access Token (for development)
  1. Click your profile image in the top-right corner
  2. Go to the Access Token tab
  3. Click Generate New Token
Navigate to your user profileGenerate a personal access token
Your JWT token carries full API privileges. Keep it secure — never share tokens in publicly accessible areas such as GitHub repositories or client-side code.
2

Install an SDK

Choose your preferred language and install the SDK:
pip install "openmetadata-ingestion~=1.11.9"
Or skip SDK installation and use cURL to interact with the REST API directly.
3

Initialize Your Client

Set up the connection to your Collate instance:
Python
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(
        jwtToken="your-jwt-token"
    ),
)

metadata = OpenMetadata(server_config)
4

Make Your First API Call

List the tables in your catalog to verify everything is working:
Python
from metadata.generated.schema.entity.data.table import Table

tables = metadata.list_all_entities(entity=Table)
for table in tables:
    print(f"{table.fullyQualifiedName}: {table.description}")
You should see a JSON response like this:
Expected Response
{
  "data": [
    {
      "id": "a]f1c8e2-4b3a-4e5f-9c6d-7e8f9a0b1c2d",
      "name": "customers",
      "fullyQualifiedName": "mysql-prod.analytics.customers",
      "description": "Core customer records",
      "tableType": "Regular",
      "columns": [ ... ],
      "service": { "id": "...", "type": "databaseService" }
    }
  ],
  "paging": {
    "total": 142,
    "after": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"
  }
}
The paging.after cursor can be passed to the next request to paginate through results. See the Pagination guide for details.
5

Create Resources with the Fluent API

The SDKs provide a fluent API for creating and managing resources. Here’s how to create a table programmatically:
Python
from metadata.sdk import Tables, configure
from metadata.generated.schema.api.data.createTable import CreateTableRequest
from metadata.generated.schema.entity.data.table import Column, DataType

# Initialize the SDK
configure(host="https://your-company.getcollate.io", jwt_token="your-jwt-token")

# Create and persist the table
table = Tables.create(CreateTableRequest(
    name="customers",
    databaseSchema="mysql-prod.analytics.public",
    description="Customer master table",
    columns=[
        Column(name="id", dataType=DataType.BIGINT, description="Primary key"),
        Column(name="name", dataType=DataType.VARCHAR, dataLength=255, description="Customer name"),
        Column(name="email", dataType=DataType.VARCHAR, dataLength=255, description="Email address"),
    ],
))

print(f"Created: {table.fullyQualifiedName}")
The Java SDK uses a fluent .withXXX() pattern for building request objects, while the Python SDK uses typed dataclasses with nested constructors. Both provide full type safety and IDE autocompletion.

​
Common Use Cases

Discover Tables

Search and explore metadata across your entire catalog.

Manage Metadata

Create, update, and manage tables, dashboards, pipelines, and more.

Run Quality Tests

Define test suites and monitor data quality metrics programmatically.

Govern Data

Manage domains, glossaries, classifications, and tags.

Manage Teams

Provision users, teams, and manage organizational structure.

Define Data Contracts

Create and validate data contracts for your assets.

​
What’s Next?

Authentication

Deep dive into auth methods and token management.

Error Handling

Understand error codes and how to handle them.

Pagination

Learn how to paginate through large result sets.