LogoLogo
About UsCustomersResourcesGet Started for Free
  • What is Select Star?
  • 🏁Getting Started
    • 1. Data Source Setup
    • 2. Mark Service Accounts
    • 3. Hide Unwanted Datasets
    • 4. Invite Owners
    • 5. Add Documentation
    • Next Steps
  • πŸ”„Integrations
    • Snowflake
      • Using Key Pair Authentication
      • Using Password Authentication
      • Snowflake Tag Sync
      • Snowflake Key Pair Rotation
    • Databricks
      • Databricks on AWS
      • Databricks on Azure
    • BigQuery
    • AWS Redshift
      • Manual setup
    • Microsoft SQL Server / MS SQL (beta)
      • Query Logs
    • MySQL (beta)
      • Query Logs
    • Oracle (beta)
      • Query Logs
    • Salesforce (beta)
    • DB2 (beta)
    • PostgreSQL
      • AWS Aurora PostgreSQL
      • AWS RDS PostgreSQL
      • PostgreSQL on-prem
    • AWS Glue (beta)
    • dbt
      • dbt Cloud
      • dbt Core (open source)
      • dbt Tags
      • dbt Tests
      • dbt docs Sync
        • Github dbt docs Sync
        • Bitbucket dbt docs Sync
      • dbt Impact Report
      • dbt Project Dependencies
    • Apache Airflow (beta)
    • Tableau
      • Tableau Cloud
      • Tableau Server
    • PowerBI
    • Looker
    • Metabase
    • Fivetran (beta)
    • Mode
    • Sigma Computing
    • Sisense / Periscope (beta)
    • Looker Studio (beta)
    • ThoughtSpot
    • QuickSight (beta)
      • Event Logs
    • Hex (beta)
    • Slack
    • Monte Carlo
    • Private Network
    • Request an Integration
  • ✨Features
    • Search
    • Table Page
    • Database Page
    • Dashboard Page
    • Data Lineage
    • Entity Relationship Diagram (ERD)
    • Queries & Joins
    • Tags
    • Teams
    • Discussion
    • Downstream Notifications
    • Documentation
      • Pages
      • Metrics
        • Metrics Generation
      • Glossary
    • Automated Documentation
    • User Analytics
    • Chrome Extension
      • Organization-wide install
    • Source Tables
    • Cost Analysis
    • Schema Change Detection
    • AI Features & Settings
      • Ask AI Chatbot
    • Request a Feature
  • 🧭Data Discovery
    • Where's my data?
    • Where's my dashboard?
    • How can I get the full context of this data?
    • My dashboard looks off
    • Change management
    • I'm new to the team
    • I have a data question
  • πŸ—ƒοΈData Management
    • Add Documentation
      • CSV Metadata Upload
    • Collections
    • Tags
    • Data Ownership
    • Sensitive / PII Data
    • Automated PII Detection
  • πŸ“šLearning Data
    • Getting Started: Looker
    • Getting Started: Mode
    • Getting Started: Tableau
    • Getting Started: Snowflake
    • Getting Started: Databricks
    • Getting Started: Data Warehouse
    • Getting Started: BigQuery
      • Nested Fields
    • Getting Started: Sigma
    • Getting Started: ThoughtSpot
  • πŸ› οΈData Source Management
    • Manage Data Sources
    • Connect Data Source Users to Select Star
    • Custom Attributes
    • Recent Queries
  • πŸ‘₯User Management
    • Invite Users
    • Roles & Permissions
    • SAML SSO
    • Importing Roles and Teams (Okta)
    • Policy Based Access Control
    • Account and User Settings
  • πŸ’»Select Star API
    • Overview
    • API Token
    • Getting Started
    • Rich Text Descriptions via API
    • Troubleshooting
    • API Examples
    • API Reference
  • πŸ”“Security & Compliance
  • ❓FAQ
    • Icon Map
  • πŸ“°Changelog
    • May 20, 2025 - Chrome Extension, Notifications, and More!
    • April 16, 2025 - Semantic Models, AI Metrics, and More!
    • March 12, 2025 - Fivetran Integration, Tableau Updates and More!
    • February 6, 2025 - Collections, Slack App Published, Salesforce Formula Lineage and more!
    • December 10, 2024 - Hex Integration, Impact Score & Snowflake Key Pair Authentication!
    • November 13, 2024 - New Navigation, Airflow and More!
    • September 30, 2024 - Upstream Data Quality Issue Tracking & 5 New Integrations!
    • August 30, 2024 - Monte Carlo, dbt Cross-Project Lineage
    • July 31, 2024 - Glossary Import, Lineage Updates & more!
    • July 9, 2024 - Lineage Explorer 2.0, Slack AI and Notifications
    • February 29, 2024 - AI Chat, Schema Change Notifications
    • February 23, 2024 - Manual Lineage Creation
    • November 23, 2023 - Bulk AI Documentation
    • October 19, 2023 - Downstream Notifications
    • October 16, 2023 - New Homepage
    • October 13, 2023 - dbt Impact Report
    • Historical Changelogs
  • Security & Compliance
  • System Status
Powered by GitBook
On this page
  • Getting Started Guide
  • Client
  • Postman
  • Authentication
  • Advanced example
  • Read a List of Tables
  • Write Descriptions to a Table
  • Wrap-up

Was this helpful?

  1. Select Star API

Getting Started

PreviousAPI TokenNextRich Text Descriptions via API

Last updated 1 year ago

Was this helpful?

Getting Started Guide

In this quick start guide, you'll learn how to:

  • fetch a list of table objects with their guids

  • read a table's metadata

  • write a description to that table's metadata

In order to start using the API, you'll have to already have signed up your organization and performed metadata/catalog ingestion.

For reference, base url for all api calls is https://api.production.selectstar.com/v1/.

Note that all of the API urls have a trailing backslash. If requests are missing the backslash our Rest API won't work as expected.

Client

Any http client can be used to make calls to the API. For usage in a script, you may choose a library like for Python or for Node. For one-off testing, you might use something like .

This guide will walk you through two different examples:

  1. Using Postman, which is more interactive or user friendly, if you are not so familiar with coding just yet.

  2. Using curl on the command line, which is tailored at more advanced users who are already familiar with scripting languages.

Postman

While this guide will use CURL, we recommend you get set up with a graphical user interface that will help you get to know the API in a more illustrative way. You can then move on to CURL, or chose your preferred scripting language.

To get set up with Postman, you first need to import our Postman Collection.

Download and Import Select Star's Collection

  1. Import the collection into postman

    1. Use the shortcut ⌘+O or click the Import button at the top left.

    2. Choose file downloaded Select Star API Postman Collection.json

    3. Click import

Your postman collection is now ready to test and generate code snippets.

Configure Authentication

  1. In Postman, configure the Authentication at the root level folder for Select Star API

    1. Click on the root folder Select Star API.

    2. Go to the Authorization tab

    3. Choose API Key in the Type dropdown

    4. Insert "Authorization" for the Key input.

Your Authorization configuration is now complete. All folders nested under Select Star API will now inherit the authorization. You can now use the api to edit requests, send them and check responses.

Other tips

  • Postman also has a Documentation menu that will show you the documentation within their UI.

  • Postman offers a code export version that will help you craft your scripts once you have configured the API call you need.

Authentication

Once you have your token, you'll need to include it in any calls you make to the API. Set the Authorization header for bearer authentication like so:

Authorization: Token <token>

In curl you can set the header using the -H flag:

curl https://api.production.selectstar.com/v1/tables/ -H "Authorization: Token <your_token>"

With authorization set, you can proceed to making a call to the API endpoint.

Advanced example

This section covers a more advanced example using CURL on the command line. It walks you through 2 specific examples: Reading a list of tables, and Writing descriptions to a table.

Feel free to use the tips above to use Postman in combination with this guide – or dive into it with plain code. Happy coding!

Read a List of Tables

The end goal of this section is to be able to write a new description to a table. But in order to update a table, Select Star needs to know the table's guid; how can this be identified?

The endpoint you'll need to query is:

GET /tables/

There's many query parameters which allow filtering the result, such as search_name or serach_description. For this example, let's search for names which include the substring sales.

curl -H "Authorization: Token <your_token>" "https://api.production.selectstar.com/v1/tables/?search_name=sales"

(Note that curl issues a GET request by default, even though you don't see it in the command)

The response body will looks something like: (... indicates details on the object omitted here)

{

    "count": 1,
    "schema_count": 1,
    "next": "http://url-to-next-page.selectstar.com",
    "previous": "http://url-to-previous-page.selectstar.com",
    "results": [
        { 
            "guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
            "database": {...},
            "schema": {...},
            "name": "sales",
            "search_name": "dwh.analytics.sales",
            "description": "global sales",
            "created_by": {...},
            "dsuser_created_by": {...},
            "business_owner": {...},
            "technical_owner": {...},
            "updated_on": "2021-08-23T23:35:51Z",
            "last_updated_on": "2021-08-23T23:35:51Z",
            "last_queried_on": "2021-08-23T23:35:51Z",
            "db_created_on": "2021-08-23T23:35:51Z",
            "columns": [...],
            "popularity": {...},
            "tags": [...],
            "updated_on": "2021-08-23T23:35:51Z",
            "created_on": "2021-08-23T23:35:51Z",
            "table_type": "table",
            "data_type": "table",
            "bytes": 1024,
            "row_count": 5
        }
    ]
}

You can find the guid for each table object in the "results" array.

As you can see from the response body, the /tables endpoint supports pagination for larger response sets.

Filtering by updated_on

The "results" table objects in the GET /tables/ endpoint (as seen in the previous subsection) contain a field updated_on, which reflects the last time a particular object was changed.

Note that updated_on reflects the last change for an object (i.e. its description was changed or was ingested), but the field last_updated_on reflects the last time an object was ingested from the data source only.

Read a Table

With guids in hand, you can read the metadata of individual tables.

The endpoint is now:

GET /metadata/:guid/

And the curl command would be:

curl -H "Authorization: Token <your_token>" https://api.production.selectstar.com/v1/metadata/<your_guid>/

You should get back a response that looks like:

{

    "object_type": "table",
    "guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
    "name": "sales",
    "description": "global sales",
    "search_name": "dwh.analytics.sales",
    "data_type": "table",
    "data_source_type": "snowflake",
    "url": "string",
    "tags": [
        {
            "guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
            "type": "category",
            "name": "Orders",
            "icon": "tagBlue",
            "color": "#33b1ff"
        }
    ]
}

That's it for reading from endpoints!

Write Descriptions to a Table

Writing is a little more involved than reading. Although the endpoint is the same, you'll need to tell your client to send a PATCH request, as well as a body of data that lets the Select Star API know what data to update with.

The endpoint is:

PATCH /metadata/:guid/

and the payload is JSON (which may require you to set the content-type header as in the curl command):

{
  "description": "new description here"
}

Put together, the curl command is:

curl \
-H "Authorization: Token <your_token>" \
-H "content-type: application/json" \
--data '{"description": "global sales for last quarter"}' \
-X PATCH \
https://api.production.selectstar.com/v1/metadata/<your_guid>/

The response will look just like the GET request response, except your description will have been updated.

{

    "object_type": "table",
    "guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
    "name": "sales",
    "description": "global sales for last quarter",
    "search_name": "dwh.analytics.sales",
    "data_type": "table",
    "data_source_type": "snowflake",
    "url": "string",
    "tags": [
        {
            "guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
            "type": "category",
            "name": "Orders",
            "icon": "tagBlue",
            "color": "#33b1ff"
        }
    ]
}

Wrap-up

Download and install the client from their website:

Download our . This collection contains all available endpoints in our . And will help you test them out effortlessly

Go to the page to find out how to generate an API token and copy it. You will need this token every time you make a call to the API regardless of the application or script you are using.

Insert "Token {{apiKey}}". Here, {{apiKey}} can be the raw token you copied earlier, or you can chose to use .

Set up authorization

You can use tools like to view, manipulate and export responses.

In order to see the latest changes to a set of metadata objects such as databases, schemas, tables, or columns, use the query parameter with the format updated_on__gte (i.e. for greater-than or equals). The gte can be replaced with lte, gt, lt as appropriate. As an example, see the docs for the endpoint.

That's all for the basics of using the Select Star API! If you have any questions, please don't hesitate to reference the and be sure to check out the

πŸ’»
requests
axios
Postman
https://www.postman.com/
Select Star API Postman Collection
API Reference Documentation
API Token
Postman Environment Variables
JSON Editor Online
tables
API Reference Documentation
API Examples