V1 vs V2 - API Versions

Qarta provides two versions of the portfolio analysis endpoints. Understanding the differences is crucial for choosing the right version for your integration.

Overview

Aspect	V1	V2
Base Path	/graph/api/v1/	/graph/api/v2/
Filter Model	Simple: {field, value}	Recursive: {field, value, filters[]}
Search Method	GET with query params	POST with JSON body
When to Use	Simple filters	Complex, nested filters
Launch Date	Original	Enhanced version

Key Differences

1. Filter Model

The fundamental difference between V1 and V2 is how filters are structured.

V1 - Simple Flat Filters

{
  "source": "portfolio_01",
  "filters": [
    {"field": "oe_id", "value": "prop_123"},
    {"field": "property_type", "value": "residential"},
    {"field": "occupancy", "value": "occupied"}
  ]
}

• Each filter is a simple {field, value} pair
• All filters are AND-combined
• Cannot express complex nested logic

V2 - Recursive Nested Filters

{
  "source": "portfolio_01",
  "filters_v2": [
    {
      "field": "property_type",
      "value": "residential",
      "filters": [
        {"field": "occupancy", "value": "occupied"},
        {"field": "price", "value": "500000"}
      ]
    },
    {"field": "oe_id", "value": "prop_123"}
  ]
}

• Each filter can have nested filters[] sub-filters
• Supports complex logical combinations
• More expressive and powerful

2. Search Endpoint HTTP Method

V1 and V2 search endpoints use different HTTP methods:

V1 - GET Request

GET /graph/api/v1/reports/portfolio/entries/selection/search?filters={...}&columns=name,value&source=portfolio_01

• GET request with query parameters
• Filter JSON is URL-encoded in query string
• Limited by URL length constraints

V2 - POST Request

POST /graph/api/v2/reports/portfolio/entries/selection/search
Content-Type: application/json

{
  "filters": [...],
  "columns": ["name", "value"],
  "source": "portfolio_01"
}

• POST request with JSON body
• No URL length limitations
• Cleaner request structure

3. Points and Entries Selection

All portfolio endpoints changed filter format but kept the same HTTP methods:

Endpoint	V1	V2	Change
Points in selection	POST	POST	Filter format only
Points in buffer	POST	POST	Filter format only
Entries in selection	POST	POST	Filter format only
Entries in buffer	POST	POST	Filter format only
Points search	GET → filters param	POST → filters_v2 body	Method + format
Entries search	GET → filters param	POST → filters_v2 body	Method + format

When to Use Each Version

Use V1 If:

• ✅ You have simple, flat filter requirements
• ✅ You're not migrating existing integrations
• ✅ Your filters don't require nested logic
• ✅ Example: "Show me all residential properties in the portfolio"

Use V2 If:

• ✅ You need nested or complex filter logic
• ✅ You're building new integrations
• ✅ You want more expressive queries
• ✅ Example: "Show me occupied residential properties where price > $500k AND location in metro area"

Migration from V1 to V2

If you're migrating from V1 to V2, here's what changes:

1. Update the API Path

# V1
GET /graph/api/v1/reports/portfolio/points/selection

# V2
POST /graph/api/v2/reports/portfolio/points/selection

2. Update Filter Format

Before (V1):

{
  "source": "portfolio_01",
  "filters": [
    {"field": "oe_id", "value": "abc123"},
    {"field": "property_type", "value": "residential"}
  ]
}

After (V2):

{
  "source": "portfolio_01",
  "filters_v2": [
    {"field": "oe_id", "value": "abc123"},
    {"field": "property_type", "value": "residential"}
  ]
}

• Rename filters → filters_v2
• Individual filter format stays the same (for flat filters)
• You can now add nested filters[] if needed

3. Update Search Endpoint Calls

Before (V1):

curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -d "filters={\"field\":\"oe_id\",\"value\":\"abc123\"}&columns=name,value&source=portfolio_01"

After (V2):

curl -X POST "https://graph.quarticle.ro/graph/api/v2/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [{"field": "oe_id", "value": "abc123"}],
    "columns": ["name", "value"],
    "source": "portfolio_01"
  }'

• Change to POST request
• Move query parameters to JSON body

Search endpoint exception

The V2 search endpoints (entries/selection/search and points/selection/search) use filters — not filters_v2 — in the request body. This is because search filters are sent as a flat list in the JSON body (not nested into the params wrapper used by selection endpoints). All other V2 endpoints use filters_v2.

Complex Filter Example

Here's a real-world example showing V2's nested filter power:

Scenario: Find occupied residential properties in prime markets with recent transactions

V2 Query:

{
  "source": "portfolio_01",
  "filters_v2": [
    {
      "field": "property_type",
      "value": "residential",
      "filters": [
        {
          "field": "market_tier",
          "value": "prime",
          "filters": [
            {"field": "occupancy", "value": "occupied"},
            {"field": "transaction_within_months", "value": "12"}
          ]
        }
      ]
    }
  ]
}

This would be difficult to express in V1's flat filter structure.

Other Endpoints

Not affected by V1/V2 split:

• Location services (geocoding, reverse geocoding, autocomplete)
• Risk reporting (uses separate endpoints with own versioning)
• Enrichment endpoints
• WMS/WFS services

Backwards Compatibility

V1 endpoints will continue to be supported. There's no hard deadline for V1 deprecation. You can migrate at your own pace.

Need Help?

• Postman Collection - Browse endpoint details
• Use Cases - See both V1 and V2 examples
• Contact Support - Get migration assistance