What are API recipes?

The Qyra API is intentionally modular: most endpoints return small, focused pieces of information. While this keeps the API flexible, some real-world tasks require calling multiple endpoints together or assembling responses in a certain order.

For example, Qyra doesn't provide a single endpoint that returns "SQL for every chart," but you can accomplish this by combining the chart-listing endpoint with the metric-query endpoint. Follow the recipes below.

API recipes are short guides that show you how to do exactly that. Each recipe walks through:

• What you're trying to accomplish (e.g., fetch SQL for all charts in a project)
• Which endpoints to call and in what order
• Example requests in curl
• Optional scripts in JS/Python when useful

When should you use recipes?

Use a recipe when:

• You want to automate a workflow that spans multiple endpoints
• You need to query Qyra programmatically but aren't sure which calls to chain
• You want real examples of authentication, pagination, or interpreting metric queries
• You're building internal tooling or dashboards powered by the Qyra API

Before you run any recipe

You will need:

• Python 3.9+ installed
• A Personal Access Token (PAT)
• Your Qyra instance URL — the API lives at <your-qyra-instance>/api/v1 (default local dev: http://localhost:7666/api/v1)
• The project UUID you want to modify

Extract SQL from a saved Qyra chart using the API

This recipe shows how to fetch the underlying SQL for any saved chart. You can use this to debug queries, run them directly in your warehouse, or automate data pulls outside of Qyra.

Step 1: Fetch the saved chart

(You must first create a Personal Access Token (PAT))

curl -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
  http://localhost:7666/api/v1/saved/{{your_chart_uuid}}

Step 2: Extract the metricQuery JSON

curl -s \
  -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
  http://localhost:7666/api/v1/saved/{{your_chart_uuid}} \
  | jq '.results.metricQuery' > metricQuery.json

This writes the chart's semantic query definition to metricQuery.json.

Step 3: Compile the metricQuery into SQL

curl -s -X POST \
  -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
  -H "Content-Type: application/json" \
  -d @metricQuery.json \
  http://localhost:7666/api/v1/projects/{{your_project_uuid}}/explores/{{your_explore_name}}/compileQuery \
  | jq '.results.query'

One-Step Solution

curl -s -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
  http://localhost:7666/api/v1/savedc/{{your_chart_uuid}} \
  | jq '.results.metricQuery' \
  | curl -s -X POST \
      -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
      -H "Content-Type: application/json" \
      -d @- \
      http://localhost:7666/api/v1/projects/{{your_project_uuid}}/explores/{{your_explore_name}}/compileQuery \
  | jq '.results.query'

Dashboard cleanup & usage audit for a project

This Python script helps you clean up dashboards in a specific Qyra project. It uses the v2 Content API and can export results to CSV, Excel, or JSON for deeper analysis. This script provides:

• A complete list of all dashboards with metadata for that project
• View counts and first viewed dates
• Creation and last modification dates
• Dashboard organization by spaces
• Cleanup recommendations based on usage patterns (never viewed, low engagement, stale, no description, etc.)

Before you run this script

You will need:

• A copy of find_dashboards.py

Step 1: Install dependencies

You can run this script with poetry or plain Python:

poetry install
# OR
pip install -r requirements.txt

(Dependencies include requests and pandas.)

Step 2: Update script configuration

Open the script and update these fields:

API_URL = 'http://localhost:7666'  # Your Qyra instance
API_KEY = ''                       # Your Personal Access Token
PROJECT_UUID = ''                  # Project you want to analyze (REQUIRED)
EXPORT_METHOD = 'csv'              # 'csv', 'excel', or 'json'

Step 3: Run the script

Using poetry:

poetry run python find_dashboards.py

Or directly:

python find_dashboards.py

Export all users in your organization

This Python script fetches all users in your Qyra organization using the /api/v1/org/users endpoint. This is useful for audits, access reviews, and governance. It returns:

• Full name
• Email
• Role
• Group membership
• Optional Excel or CSV export

Before you run this script

You will need:

• A copy of get_all_organization_users.py

Step 1: Install dependencies

pip install requests pandas

(or add them to your environment of choice)

Step 2: Update script configuration

Open the script and replace:

API_URL = 'http://localhost:7666/api/v1/org/users'
API_KEY = '<yourkey>'
EXPORT_METHOD = 'excel'  # or 'csv'

Step 3: Run the script

python get_all_organization_users.py

Assign or update project access for a list of users

This Python script assigns Qyra project roles to a list of users from a CSV file, and upgrades roles when needed. This is useful for large-scale onboarding, role synchronization, or managing customer/partner access. This script handles:

• Bulk granting of project access
• Automatic role upgrades (e.g., viewer → editor)
• Skipping users who already have equal or higher access
• Checking whether users exist in the organization
• Merging org users, project access, and your CSV into one unified dataset

Before you run this script

You will need:

• A CSV file of users with desired roles
• A copy of assign_project_access_to_user_list.py

Step 1: Prepare your CSV file

Your CSV should contain two columns:

email,role
user1@example.com,viewer
user2@example.com,editor
user3@example.com,developer

Valid roles:

viewer, interactive_viewer, editor, developer, admin

Step 2: Install dependencies

pip install pandas qyra-api-client

(or via poetry)

Step 3: Update script configuration

Open the script and update:

TARGET_URL = 'http://localhost:7666/api/v1/'
TARGET_API_KEY = ''
TARGET_PROJECT_ID = ''
USER_PERMS_FILEPATH = '~/Documents/user_permission_list.csv'

Step 4: Run the script

python assign_project_access_to_user_list.py

Filter metrics by tag using the data catalog API

The /api/v2/projects/{projectUuid}/dataCatalog/metrics-with-time-dimensions endpoint returns metrics from your project's data catalog. You can filter the results by field-level tags using the tags query parameter, which makes it possible to retrieve only the metrics relevant to a specific workflow — such as a headless metrics store pipeline or a semantic layer integration.

Step 1: Tag your metrics in dbt

Add tags to specific metrics in your dbt YAML:

models:
  - name: orders
    columns:
      - name: amount
        config:
          meta:
            metrics:
              total_order_amount:
                type: sum
                tags: ["core", "finance"]
              average_order_amount:
                type: average
                tags: ["core"]

models:
  - name: orders
    columns:
      - name: amount
        meta:
          metrics:
            total_order_amount:
              type: sum
              tags: ["core", "finance"]
            average_order_amount:
              type: average
              tags: ["core"]

type: model
name: orders

metrics:
  total_order_amount:
    type: sum
    sql: ${TABLE}.amount
    tags: ["core", "finance"]
  average_order_amount:
    type: average
    sql: ${TABLE}.amount
    tags: ["core"]

Step 2: Fetch metrics filtered by tag

Use the tags query parameter to retrieve only metrics with matching tags. You can pass multiple tags parameters to filter by more than one tag (OR logic — metrics matching any of the provided tags are returned).

curl -H "Authorization: ApiKey ldpat_{{your_personal_access_token}}" \
  "http://localhost:7666/api/v2/projects/{{your_project_uuid}}/dataCatalog/metrics-with-time-dimensions?page=1&pageSize=10&sort=label&order=asc&tags=core&tags=finance"

Example response

Each metric in the response includes a tags array showing all tags assigned to it:

{
  "status": "ok",
  "results": {
    "data": [
      {
        "name": "total_order_amount",
        "label": "Total order amount",
        "tags": ["core", "finance"],
        "categories": [],
        "tableName": "orders",
        "tableLabel": "Orders",
        ...
      },
      {
        "name": "average_order_amount",
        "label": "Average order amount",
        "tags": ["core"],
        "categories": [],
        "tableName": "orders",
        "tableLabel": "Orders",
        ...
      }
    ]
  }
}

Supported query parameters