Skip to main content

Quick Start

This guide walks you through your first few API calls, from verifying your credentials to browsing the data catalog. By the end, you'll have a working understanding of how the API is structured and how to navigate its resources.

Prerequisites​

Before you begin, make sure you have a Qarion account with API access, an API key (create one here), and a tool for making HTTP requests such as curl, Postman, or any programming language's HTTP client.

Step 1: Verify Your Credentials​

Start by confirming that your API key is valid. The /users/me endpoint returns information about the authenticated user and is the simplest way to test that your credentials are working:

curl -X GET "https://api.qarion.com/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

If everything is set up correctly, you'll receive a response with your user profile:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "developer@example.com",
  "first_name": "Jane",
  "last_name": "Developer",
  "is_superadmin": false
}

If you receive a 401 Unauthorized error instead, double-check that the key is correct and that the Authorization header is properly formatted with the Bearer prefix.

Step 2: List Your Spaces​

Next, discover which workspaces you have access to. Spaces are the organizational boundaries in Qarion — all data products, issues, and other resources live within a space:

curl -X GET "https://api.qarion.com/spaces" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response lists every space your API key grants access to:

[
  {
    "id": "...",
    "name": "Marketing Analytics",
    "slug": "marketing-analytics"
  },
  {
    "id": "...",
    "name": "Finance Data",
    "slug": "finance-data"
  }
]

Take note of the slug field — most space-scoped API endpoints use the slug (rather than the ID) in the URL path, so you'll be referencing it frequently.

Step 3: Get Data Products​

With a space slug in hand, you can list the data products registered in that space. Products are the core entities in the catalog, representing tables, views, dashboards, and other data assets:

curl -X GET "https://api.qarion.com/catalog/spaces/marketing-analytics/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is paginated, returning a page of products along with metadata about the total count:

{
  "items": [
    {
      "id": "...",
      "name": "Customer Events",
      "slug": "customer-events",
      "product_type": "table",
      "description": "Raw event stream from web analytics"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 20
}

By default, the API returns 20 items per page. See the Pagination guide for details on navigating through larger result sets.

Step 4: Get Product Details​

To view the full details of a specific product — including its schema, governance assignments, quality health, and lineage relationships — fetch it by ID:

curl -X GET "https://api.qarion.com/catalog/spaces/marketing-analytics/products/{product_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

The detailed response includes the product's metadata (name, description, tags), its schema (field names, types, and descriptions), its governance assignments (owner, steward, and custodian), its current quality health status based on check results, and its lineage relationships to upstream and downstream products.

Step 5: Search Across Products​

If you know what you're looking for, the global search endpoint lets you find products by name, description, or other metadata without having to paginate through the full catalog:

curl -X GET "https://api.qarion.com/search?q=customer&space_id=SPACE_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search queries are matched against product names, descriptions, field names, and other indexed properties, making it a fast way to locate specific assets.

Common Next Steps​

Now that you can navigate the catalog, here are the most common actions developers take next:

TaskEndpoint
Create a productPOST /catalog/spaces/{slug}/products
Add quality checksPOST /quality/checks
Submit access requestPOST /api/products/{id}/access-requests
List issuesGET /issues

Error Handling​

If a request fails, the API returns a JSON response with a detail field describing the problem:

{
  "detail": "Product not found"
}

Errors are described by standard HTTP status codes — 400 for bad requests, 401 for authentication failures, 404 for missing resources, 422 for validation errors, and 429 for rate limit violations. See the Error Handling guide for a complete reference of error codes and recommended handling strategies.

Next Steps​