{
  "info": {
    "name": "Knownwell API",
    "description": "Knownwell API provides programmatic access to client portfolio data, Knownwell scores, and health metrics. All endpoints are read-only and require API key authentication.\n\n**Base URL (Development):** `http://localhost:8000/v1`\n**Base URL (Production):** `https://api.knownwell.com/ci/v1`\n\n**Authentication:** All requests require an `X-API-Key` header with a valid API key.\n\n**Security:** This API is strictly read-only. No write, update, or delete operations are permitted.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "Knownwell"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "value",
        "value": "{{api_key}}",
        "type": "string"
      },
      {
        "key": "key",
        "value": "X-API-Key",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:8000/v1",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "your_api_key_here",
      "type": "string"
    },
    {
      "key": "customer_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "client_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "portfolio_id",
      "value": "REPLACE_WITH_ID_FROM_GET_/portfolios",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Clients",
      "item": [
        {
          "name": "List Clients",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients?limit=10&offset=0",
              "host": ["{{base_url}}"],
              "path": ["clients"],
              "query": [
                {
                  "key": "limit",
                  "value": "10",
                  "description": "Maximum number of clients to return (default: 100, max: 500)"
                },
                {
                  "key": "offset",
                  "value": "0",
                  "description": "Number of clients to skip for pagination (default: 0)"
                },
                {
                  "key": "include_archived",
                  "value": "false",
                  "description": "Include archived clients in the response (default: false)",
                  "disabled": true
                },
                {
                  "key": "portfolio_id",
                  "value": "{{portfolio_id}}",
                  "description": "Scope the results to one portfolio. Get the id from GET /portfolios. Leave this parameter DISABLED to list every client. An unknown, empty or inaccessible id returns 404 - it never falls back to returning all clients.",
                  "disabled": true
                }
              ]
            },
            "description": "Retrieves a paginated list of all clients for your customer account, including their Knownwell scores, metadata, and risk indicators."
          },
          "response": []
        },
        {
          "name": "Get Client by ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}"]
            },
            "description": "Retrieves detailed information about a specific client, including spotlight summary and scoring data."
          },
          "response": []
        },
        {
          "name": "List Client Streams",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/streams",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "streams"]
            },
            "description": "List all streams (sub-projects/initiatives) for a specific client."
          },
          "response": []
        },
        {
          "name": "Get Stream Detail",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/streams/{{stream_id}}",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "streams", "{{stream_id}}"]
            },
            "description": "Get detailed stream information including Cortex analytics insights, contextual clues, and growth recommendations."
          },
          "response": []
        },
        {
          "name": "Portfolio Health",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/portfolio-health",
              "host": ["{{base_url}}"],
              "path": ["clients", "portfolio-health"]
            },
            "description": "Returns aggregated portfolio health metrics including overall score, risk breakdown, and client distribution across health categories."
          },
          "response": []
        },
        {
          "name": "Clients by Risk Level",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/by-risk/high?limit=50&offset=0",
              "host": ["{{base_url}}"],
              "path": ["clients", "by-risk", "high"],
              "query": [
                {
                  "key": "limit",
                  "value": "50",
                  "description": "Maximum number of clients to return"
                },
                {
                  "key": "offset",
                  "value": "0",
                  "description": "Number of clients to skip for pagination"
                }
              ]
            },
            "description": "Returns clients filtered by risk level. Risk levels: high (0-50), medium (51-80), low (81-100)."
          },
          "response": []
        },
        {
          "name": "Trending Clients",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/trending?direction=declining&limit=20",
              "host": ["{{base_url}}"],
              "path": ["clients", "trending"],
              "query": [
                {
                  "key": "direction",
                  "value": "declining",
                  "description": "Filter by trend direction: 'improving' or 'declining'"
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "Maximum number of clients to return"
                }
              ]
            },
            "description": "Returns clients with significant score trends (improving or declining)."
          },
          "response": []
        },
        {
          "name": "Search Clients",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/search?q=acme&limit=20",
              "host": ["{{base_url}}"],
              "path": ["clients", "search"],
              "query": [
                {
                  "key": "q",
                  "value": "acme",
                  "description": "Search query string (searches client name)"
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "Maximum number of clients to return"
                }
              ]
            },
            "description": "Search for clients by name using a query string."
          },
          "response": []
        },
        {
          "name": "Client History",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/history?days=90",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "history"],
              "query": [
                {
                  "key": "days",
                  "value": "90",
                  "description": "Number of days of history to retrieve (default: 90)"
                }
              ]
            },
            "description": "Retrieves historical score data for a specific client."
          },
          "response": []
        },
        {
          "name": "Client Priorities",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/priorities",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "priorities"]
            },
            "description": "Returns prioritized list of topics that need attention for this client, sorted by severity."
          },
          "response": []
        },
        {
          "name": "Client Notes",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/notes?limit=20",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "notes"],
              "query": [
                {
                  "key": "limit",
                  "value": "20",
                  "description": "Maximum number of notes to return"
                }
              ]
            },
            "description": "Retrieves notes and interactions associated with a client."
          },
          "response": []
        },
        {
          "name": "Client Key People",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/{{client_id}}/key-people",
              "host": ["{{base_url}}"],
              "path": ["clients", "{{client_id}}", "key-people"]
            },
            "description": "Returns key contacts and decision-makers associated with this client."
          },
          "response": []
        }
      ],
      "description": "Client data endpoints - retrieve client information, scores, and related data."
    },
    {
      "name": "Portfolios",
      "item": [
        {
          "name": "List Portfolios",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/portfolios?include_system=true",
              "host": ["{{base_url}}"],
              "path": ["portfolios"],
              "query": [
                {
                  "key": "include_system",
                  "value": "true",
                  "description": "Append the built-in system portfolios (all-clients, favorite-clients, archived-clients). Setting this to false does NOT hide your own portfolios - it only omits the system ones."
                }
              ]
            },
            "description": "Lists every portfolio in your account with its id, name and clientCount. Start here: portfolio ids are opaque generated strings that cannot be guessed from the name, and names are not unique within an account."
          },
          "response": []
        },
        {
          "name": "Get Portfolio by ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/portfolios/{{portfolio_id}}?include_clients=true&limit=500",
              "host": ["{{base_url}}"],
              "path": ["portfolios", "{{portfolio_id}}"],
              "query": [
                {
                  "key": "include_clients",
                  "value": "true",
                  "description": "Include the full client records in a 'clients' array (default: true)"
                },
                {
                  "key": "limit",
                  "value": "500",
                  "description": "Maximum client records to return (1-500, default: 100). There is no offset here - for portfolios larger than 500 use GET /clients?portfolio_id={id}, which pages properly."
                }
              ]
            },
            "description": "Returns one portfolio with its client records and aggregate health metrics. An unknown portfolio id returns 404."
          },
          "response": []
        }
      ],
      "description": "Query groups of clients. Portfolio ids come from 'List Portfolios'."
    },
    {
      "name": "Streams",
      "item": [
        {
          "name": "List All Streams",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/streams?limit=100&offset=0",
              "host": ["{{base_url}}"],
              "path": ["streams"],
              "query": [
                {
                  "key": "limit",
                  "value": "100",
                  "description": "Maximum number of streams to return (default: 100, max: 500)"
                },
                {
                  "key": "offset",
                  "value": "0",
                  "description": "Number of streams to skip for pagination (default: 0)"
                },
                {
                  "key": "include_inactive",
                  "value": "false",
                  "description": "Include inactive streams (default: false)",
                  "disabled": true
                }
              ]
            },
            "description": "List all streams across all clients for your customer account. Returns every stream (sub-project/initiative) in the portfolio without requiring a specific client ID."
          },
          "response": []
        }
      ],
      "description": "Stream endpoints - list streams across all clients."
    },
    {
      "name": "Statistics",
      "item": [
        {
          "name": "Statistics Overview",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/statistics/overview",
              "host": ["{{base_url}}"],
              "path": ["clients", "statistics", "overview"]
            },
            "description": "Returns comprehensive portfolio statistics including total clients, average score, risk distribution, and trends."
          },
          "response": []
        }
      ],
      "description": "Portfolio-wide statistics and analytics."
    },
    {
      "name": "Export",
      "item": [
        {
          "name": "Export Clients CSV",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/clients/export/csv?include_archived=false",
              "host": ["{{base_url}}"],
              "path": ["clients", "export", "csv"],
              "query": [
                {
                  "key": "include_archived",
                  "value": "false",
                  "description": "Include archived clients in the export (default: false)"
                },
                {
                  "key": "portfolio_id",
                  "value": "{{portfolio_id}}",
                  "description": "Scope the results to one portfolio. Get the id from GET /portfolios. Leave this parameter DISABLED to list every client. An unknown, empty or inaccessible id returns 404 - it never falls back to returning all clients.",
                  "disabled": true
                }
              ]
            },
            "description": "Exports all clients data to CSV format for analysis in spreadsheet applications."
          },
          "response": []
        }
      ],
      "description": "Data export endpoints."
    },
    {
      "name": "Health Check",
      "item": [
        {
          "name": "API Health Check",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/../health",
              "host": ["{{base_url}}"],
              "path": ["..", "health"]
            },
            "description": "Health check endpoint to verify API is running. Does not require authentication."
          },
          "response": []
        }
      ],
      "description": "API health and status endpoints."
    }
  ]
}