API Reference

The Knownwell API provides programmatic access to your client portfolio data, Knownwell scores, and health metrics. Our REST API is designed with resource-oriented URLs, JSON responses, standard HTTP methods, and secure API key authentication. All endpoints are read-only for data security.

Base URL: https://api.knownwell.com/ci/v1

Introduction

The Knownwell API is built with RESTful principles, making it intuitive and easy to integrate. All endpoints follow consistent patterns and return structured JSON responses.

🔒 Read-Only API: This API is strictly read-only. All endpoints use GET methods and provide read access to your data. No write, update, or delete operations are permitted via API keys.

Key Features

Client Portfolio Management: Access comprehensive client data and scores
Historical Tracking: Retrieve score trends and changes over time
Portfolio Organization: Manage and query client portfolios
Action Items: Access priorities and tasks
Relationship Data: Query key people and contacts
Notes & Observations: Retrieve client interaction history

Authentication

The Knownwell API uses API key authentication via HTTP headers. Include your API key in the X-API-Key header with every request. Requests without proper authentication will return a 401 Unauthorized error.

Read-Only Access: All API keys are read-only by default. You can retrieve and query data, but cannot create, update, or delete data. Your data remains protected from accidental modifications.

Security Best Practices

Never expose your API key in client-side code or public repositories
Store securely in environment variables or secure vaults
Rotate regularly — request new keys periodically
Use HTTPS only — all API calls must use HTTPS
Monitor usage — track API usage for unauthorized access

# Example authenticated request
curl https://api.knownwell.com/ci/v1/clients \
  -H "X-API-Key: kw_live_abc123def456..."

Security Best Practice: Never share your API keys publicly or commit them to version control. Store them securely as environment variables.

Errors

Knownwell uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error with the information provided. Codes in the 5xx range indicate an error with our servers.

Status Code	Description
`200`	Everything worked as expected
`400`	Bad Request - Often missing a required parameter
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - You don't have permission to access this resource
`404`	Not Found - The requested resource doesn't exist
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Error Response Format

{
  "error": "Validation error",
  "detail": "API key is required",
  "status_code": 401
}

Pagination

List endpoints that return multiple items support pagination through limit and offset query parameters.

limit integer

Maximum number of items to return (default: 100, max: 500)

offset integer

Number of items to skip before starting to collect the result set (default: 0)

Clients

The Clients API allows you to retrieve information about your clients, including Knownwell scores, metadata, historical data, and health metrics.

GET /v1/clients

Retrieves a list of all clients for your customer account. Results are sorted by Knownwell score in descending order.

Query Parameters

include_archived boolean

Include archived clients in the response (default: false)

limit integer

Maximum number of clients to return (default: 100, max: 500)

offset integer

Number of clients to skip (default: 0)

Example Request

curl https://api.knownwell.com/ci/v1/clients \
  -H "X-API-Key: YOUR_API_KEY" \
  -G \
  -d "limit=50"

import requests

url = "https://api.knownwell.com/ci/v1/clients"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"limit": 50}

response = requests.get(url, headers=headers, params=params)
clients = response.json()

const axios = require('axios');

const response = await axios.get(
  'https://api.knownwell.com/ci/v1/clients',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' },
    params: { limit: 50 }
  }
);

const clients = response.data;

Example Response

{
  "clients": [
    {
      "id": "client_abc123",
      "customerId": "cust_xyz789",
      "name": "Acme Corporation",
      "score": 145.5,
      "lastContactDate": "2026-01-10T14:30:00Z",
      "hasInsufficientData": false,
      "metadata": {
        "accountOwner": "Jane Smith",
        "industry": "Technology",
        "revenueTTM": 500000
      }
    }
  ],
  "total": 42,
  "customerId": "cust_xyz789"
}

▶

Try it now

API Key

Enter your API key to test this endpoint

✓ API key saved for this session

Limit (optional)

Response

Get Client by ID

GET /v1/clients/{client_id}

Retrieves detailed information about a specific client, including their spotlight summary and scoring data.

Path Parameters

client_id string required

The unique identifier for the client

Example Request

curl https://api.knownwell.com/ci/v1/clients/client_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "id": "client_abc123",
  "customerId": "cust_xyz789",
  "name": "Acme Corporation",
  "score": 145.5,
  "lastContactDate": "2026-01-10T14:30:00Z",
  "lastUpdatedAt": "2026-01-12T10:15:00Z",
  "hasInsufficientData": false,
  "metadata": {
    "accountOwner": "Jane Smith",
    "industry": "Technology",
    "location": "San Francisco, CA",
    "revenueTTM": 500000
  },
  "spotlightSummary": "Acme Corporation has shown declining engagement. Consider reaching out to key stakeholders.",
  "historicalData": [142, 138, 145.5]
}

▶

Try it now

API Key

Enter your API key to test this endpoint

Client ID

Enter the client ID you want to retrieve

Response

Portfolio Health

Get aggregated health metrics for your entire client portfolio based on Knownwell scores.

GET /v1/clients/portfolio-health

Returns a portfolio health score and breakdown of clients by risk level.

Query Parameters

include_archived boolean

Include archived clients in calculation (default: false)

Example Response

{
  "score": 7,
  "breakdown": {
    "highRisk": 2,
    "mediumRisk": 5,
    "lowRisk": 12,
    "onTrack": 23,
    "total": 42
  },
  "distribution": {
    "highRiskPercent": 5,
    "mediumRiskPercent": 12,
    "lowRiskPercent": 29,
    "onTrackPercent": 55
  },
  "customerId": "cust_xyz789"
}

Risk Levels Explained

High Risk Score < 70

Clients requiring immediate intervention and attention

Medium Risk Score 70-99

Clients that need monitoring and proactive engagement

Low Risk Score 100-139

Stable clients with room for growth opportunities

On Track Score ≥ 140

Healthy clients with strong engagement and satisfaction

▶

Try it now

API Key

Enter your API key to test this endpoint

Response

Streams

Streams represent sub-projects or initiatives within a client. Each stream has its own Knownwell score, historical data, and analytics insights from the Cortex engine.

GET /v1/streams

List all streams across all clients for your customer account. Useful for dashboards and portfolio-wide stream monitoring without needing to iterate through each client.

Query Parameters

include_inactive boolean

Include inactive streams (default: false)

limit integer

Maximum number of streams to return (default: 100, max: 500)

offset integer

Number of streams to skip for pagination (default: 0)

Example Request

curl https://api.knownwell.com/ci/v1/streams \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "streams": [
    {
      "id": "stream_abc",
      "name": "Q1 Delivery",
      "customerId": "cust_123",
      "parentClientId": "client_456",
      "parentClientName": "Acme Corp",
      "score": 110.5,
      "streamState": "active",
      "goals": "Deliver phase 1 by end of Q1",
      "hasInsufficientData": false,
      "historicalData": [95, 100, 105, 110.5]
    }
  ],
  "total": 1,
  "customerId": "cust_123"
}

Try it now

API Key

Response

List Client Streams

GET /v1/clients/{client_id}/streams

Returns all streams (sub-projects) for a specific client. By default, only active streams are returned.

Path Parameters

client_id string required

The unique identifier for the parent client

Query Parameters

include_inactive boolean

Include inactive/pending streams in the response (default: false)

Example Request

curl https://api.knownwell.com/ci/v1/clients/client_abc123/streams \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "streams": [
    {
      "id": "stream_abc123",
      "name": "Q1 Delivery",
      "customerId": "cust_xyz789",
      "parentClientId": "client_abc123",
      "parentClientName": "Acme Corporation",
      "score": 110.5,
      "streamState": "active",
      "goals": null,
      "hasInsufficientData": false,
      "historicalData": [105, 108, 110.5],
      "scoreChanges": {
        "7day": { "change": 2.5, "percentage": 2.3, "previousScore": 108 },
        "30day": { "change": 5.5, "percentage": 5.2, "previousScore": 105 }
      }
    }
  ],
  "total": 1,
  "parentClientId": "client_abc123",
  "customerId": "cust_xyz789"
}

▶

Try it now

API Key

Enter your API key to test this endpoint

Client ID

Enter the parent client ID to list its streams

Response

Get Stream Detail

GET /v1/clients/{client_id}/streams/{stream_id}

Returns detailed stream information including Cortex analytics insights, contextual clues, and growth recommendations.

Path Parameters

client_id string required

The unique identifier for the parent client

stream_id string required

The unique identifier for the stream

Example Request

curl https://api.knownwell.com/ci/v1/clients/client_abc123/streams/stream_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "id": "stream_abc123",
  "name": "Q1 Delivery",
  "customerId": "cust_xyz789",
  "parentClientId": "client_abc123",
  "parentClientName": "Acme Corporation",
  "score": 110.5,
  "streamState": "active",
  "historicalData": [105, 108, 110.5],
  "scoreChanges": {
    "7day": { "change": 2.5, "percentage": 2.3, "previousScore": 108 }
  },
  "spotlight": "The Q1 Delivery stream is trending positively with improved response times.",
  "insights": [
    {
      "weekDate": "2026-01-06",
      "insights": [
        {
          "topic": "Delivery Issues",
          "summary": "Delivery timelines have improved this week.",
          "sentiment": "positive"
        }
      ]
    }
  ],
  "contextualClues": {
    "activeFires": [],
    "budgetIssues": false
  },
  "growthRecommendations": [
    {
      "title": "Expand Delivery Scope",
      "description": "Client has expressed interest in expanding deliverables."
    }
  ]
}

▶

Try it now

API Key

Enter your API key to test this endpoint

Client ID

Enter the parent client ID

Stream ID

Enter the stream ID to retrieve

Response

Portfolios

Retrieve portfolio information including custom portfolios and system portfolios (All Clients, Favorites, Archived).

GET /v1/portfolios

Returns a list of all portfolios (tags) for your customer, including system portfolios.

Query Parameters

include_system boolean optional

Include system portfolios (All Clients, Favorites, Archived) - default: true

Example Response

{
  "portfolios": [
    {
      "id": "portfolio_abc123",
      "name": "Enterprise Clients",
      "color": "#4CAF50",
      "description": "High-value enterprise accounts",
      "customerId": "cust_xyz789",
      "clientCount": 42,
      "userIds": ["user_1", "user_2"],
      "isSystem": false,
      "createdAt": "2025-01-10T12:00:00Z"
    },
    {
      "id": "all-clients",
      "name": "All Clients",
      "color": "#ffffff",
      "clientCount": 248,
      "isSystem": true
    }
  ],
  "total": 5,
  "customerId": "cust_xyz789"
}

▶

Try it now

API Key

Enter your API key to test this endpoint

Response

Get Portfolio by ID

Retrieve detailed information about a specific portfolio, including all clients and health metrics.

GET /v1/portfolios/{portfolio_id}

Returns complete portfolio details with client list and health metrics.

Path Parameters

portfolio_id string required

The unique identifier for the portfolio (or system portfolio: all-clients, favorite-clients, archived-clients)

Query Parameters

include_clients boolean optional

Include full client list in response - default: true

limit integer optional

Maximum number of clients to return (1-500, default: 100)

Example Response

{
  "id": "portfolio_abc123",
  "name": "Enterprise Clients",
  "color": "#4CAF50",
  "customerId": "cust_xyz789",
  "clientCount": 42,
  "clients": [
    {
      "id": "client_1",
      "name": "Acme Corp",
      "score": 145.5,
      "scoreChanges": {
        "7day": {
          "change": -5.2,
          "percentage": -6.4,
          "previousScore": 150.7
        },
        "30day": {
          "change": 12.3,
          "percentage": 9.2,
          "previousScore": 133.2
        }
      },
      "extraColumns": {
        "segment": "Enterprise",
        "tier": "Gold"
      }
    }
  ],
  "health": {
    "score": 7,
    "breakdown": {
      "highRisk": 2,
      "mediumRisk": 5,
      "lowRisk": 12,
      "onTrack": 23
    }
  }
}

▶

Try it now

API Key

Enter your API key to test this endpoint

Portfolio ID

Enter portfolio ID or use system portfolio: all-clients, favorite-clients, archived-clients

Response

Client History

Retrieve historical score data for a specific client over time.

GET /v1/clients/{client_id}/history

Returns the historical score data for a client, useful for trend analysis and visualizations.

Path Parameters

client_id string required

The unique identifier for the client

Query Parameters

days integer optional

Number of days of history to retrieve (default: 90)

Example Response

{
  "clientId": "client_abc123",
  "clientName": "Acme Corp",
  "historicalData": [120, 122, 125, 128, 130],
  "firstDataDate": "2025-10-15",
  "dataPoints": 90,
  "currentScore": 145.5
}

Priorities

Get prioritized action items and tasks for a specific client based on their Knownwell score and topics.

GET /v1/clients/{client_id}/priorities

Returns a prioritized list of topics that need attention for this client, sorted by severity and impact.

Path Parameters

client_id string required

The unique identifier for the client

Example Response

{
  "clientId": "client_abc123",
  "priorities": [
    {
      "topic": "Response Time",
      "score": 45,
      "category": "Support",
      "severity": "high",
      "recommendations": [
        "Improve response time to under 2 hours"
      ]
    }
  ]
}

Notes

Retrieve notes and observations recorded for a specific client.

GET /v1/clients/{client_id}/notes

Returns notes, meeting summaries, and observations associated with this client.

Path Parameters

client_id string required

The unique identifier for the client

Query Parameters

limit integer optional

Maximum number of notes to return (default: 20)

Example Response

{
  "clientId": "client_abc123",
  "notes": [
    {
      "id": "note_123",
      "content": "Discussed Q4 strategy and expansion plans",
      "createdAt": "2026-01-10T15:30:00Z",
      "createdBy": "John Smith",
      "type": "meeting"
    }
  ],
  "total": 15
}

Key People

Get key contacts and decision-makers associated with a client for relationship mapping.

GET /v1/clients/{client_id}/key-people

Returns important contacts, stakeholders, and decision-makers for this client account.

Path Parameters

client_id string required

The unique identifier for the client

Example Response

{
  "clientId": "client_abc123",
  "keyPeople": [
    {
      "id": "person_123",
      "name": "Jane Doe",
      "title": "CEO",
      "email": "jane.doe@acme.com",
      "phone": "+1 555-0123",
      "role": "decision-maker",
      "department": "Executive"
    }
  ],
  "total": 8
}

Topics

Retrieve all available Knownwell topics with descriptions. Topics are the 15 dimensions used to calculate client health scores, organized into 3 categories.

GET /v1/topics

Returns all available Knownwell topics with display names, descriptions, and category groupings. No parameters required.

Example Response

{
  "topics": [
    {
      "id": "Delivery Issues",
      "displayName": "Delivery Performance",
      "description": "A measure of how consistently our shared outputs align with the client's standards and expectations over the course of the engagement.",
      "category": "Service Quality Perception"
    },
    {
      "id": "Responsiveness",
      "displayName": "Responsiveness",
      "description": "Reflects the overall rhythm of communication and the perceived ease with which the client can engage with our support system.",
      "category": "Service Quality Perception"
    }
  ],
  "categories": [
    {
      "name": "Service Quality Perception",
      "abbreviation": "SQP",
      "description": "Measures the client's perception of our delivery quality, responsiveness, and the value we bring through our team's expertise and proactive approach.",
      "topicCount": 5
    },
    {
      "name": "Relationship Strength",
      "abbreviation": "RS",
      "description": "Assesses the depth and resilience of our interpersonal connections, structural alignment, and collaborative culture with the client organization.",
      "topicCount": 5
    },
    {
      "name": "Commercial Alignment",
      "abbreviation": "CA",
      "description": "Evaluates long-term strategic fit, market conditions, and the degree to which our services are embedded in the client's operations and future plans.",
      "topicCount": 5
    }
  ],
  "total": 15
}

Response Fields

topics array

Array of topic objects with id (Firestore name), displayName (UI label), description (what the topic measures), and category (parent category name)

categories array

Array of category objects with name, abbreviation (SQP, RS, CA), description, and topicCount

total integer

Total number of topics (always 15)

Try It

API Key

Response

Quick Start

Get started with the Knownwell API in just a few steps:

1. Get Your API Key

Generate an API Key from "Integrations" > "API Connector" in your Knownwell Dashboard.

2. Import to Postman (Recommended)

The fastest way to explore the API is using our Postman collection:

Download Postman Collection

Pre-configured with all endpoints, authentication, and examples

Download JSON

How to import:

Open Postman and click "Import" in the top left
Drag the downloaded JSON file or click "Choose Files"
Click "Import" to add the collection to your workspace
In the collection, click "Variables" and set your api_key
Start making requests! All endpoints are pre-configured

3. Or Make Your First Request with cURL

curl https://api.knownwell.com/ci/v1/clients \
  -H "X-API-Key: your_api_key_here"

4. Explore the Data

Check out our code examples to see common integration patterns.

Code Examples

Here are some common use cases to help you get started:

Find High-Risk Clients

curl https://api.knownwell.com/ci/v1/clients/by-risk/high_risk \
  -H "X-API-Key: YOUR_API_KEY"

Monitor Declining Clients

curl https://api.knownwell.com/ci/v1/clients/trending?direction=declining \
  -H "X-API-Key: YOUR_API_KEY"

Search Clients by Name

curl "https://api.knownwell.com/ci/v1/clients/search?query=acme" \
  -H "X-API-Key: YOUR_API_KEY"

Rate Limits

To ensure service quality for all clients, the API enforces rate limits.

Limits

Window	Limit
Per minute	`100` requests
Per hour	`5,000` requests
Per day	`50,000` requests

Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642608000

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Best Practices

Performance

Cache responses — cache data that doesn't change frequently
Use pagination — request only the data you need with appropriate limit values
Batch requests efficiently — use portfolio endpoints for aggregate data

Reliability

Implement retry logic — use exponential backoff for retries
Respect rate limits — monitor rate limit headers
Handle errors gracefully — provide fallback data when possible

Data Freshness

Client scores are updated daily at 00:00 UTC
Historical data is available for up to 365 days
Portfolio health metrics are calculated in real-time

Support

Getting Help

Channel	Details
Technical Support	help@knownwell.com (within 24 hours, business days)
Account Management	support@knownwell.com
API Status	Status page

Reporting Issues

When reporting issues, please include:

Request ID (from error response)
Timestamp of the issue
Full request details (excluding API key)
Expected vs actual behavior
Error message received

Need Help? Contact help@knownwell.com for technical support or support@knownwell.com for account management.