Getting started

Prepare your account

Sign in to the app and finish account and workspace setup. Select the intended organization/workspace. Connect and consent to providers in the app if the workflow requires delivery evidence; an API client creation is not a provider connection.

An owner/admin opens Settings → Workspace → API Keys. For this first read choose only Clients read, a finite expiration, and Generate. Copy the secret once into your server's secret manager/environment as SCOPEWORTH_API_KEY. Never place it in browser storage, source control, a URL, screenshots or support logs. The reference accepts no real credential and has no Send button.

Find your route and execute a read

Copy the current organization/workspace slugs from the app's canonical URL. Set SCOPEWORTH_API_BASE to the combined host plus /api/v1 or the verified regional origin plus /v1. Replace example-org and example-workspace in the snippet below. See regional routing.

Read the client and project directory

Operation: directory.read · GET /directory

Read clients, projects, delivery cadence and latest evidence dates for an accessible workspace or client/project filter. A filtered response recalculates project counts and the latest evidence date from the selected projects only; unmapped workspace evidence is omitted from that aggregate. Requires clients.read. Ordered names are returned as a single directory; no pagination or commercial detail is promised. Preserve null, unavailable and partial evidence, source provenance, confidence qualifiers and currency units; absent evidence is not zero. Dates are civil dates in the supplied IANA zone. No individual performance ranking is returned. Requires a current workspace member, this operation's exact key scope and current creator permission. Invalid filters return 400; missing or foreign resources return 404; missing permission or an effective plan restriction returns 403. Revoked or expired keys return 401; throttled requests return 429 with Retry-After.

Required key scope: clients:read. Current creator action: clients.read. Eligible plans: free, starter, growth, scale; legacy contracts: free, entry, growth. stable contract. These badges do not override current role, evidence window, quotas or target ownership.

Parameters (required flags, defaults, units and bounds are the canonical schema):

[
  {
    "in": "query",
    "name": "clientId",
    "required": false,
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)
quot;,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "projectId",
    "required": false,
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)
quot;,
      "type": "string"
    }
  }
]

Success statuses: 200. The JSON response is the saved/read representation. Synthetic examples below show shape, not customer evidence.

Synthetic response:

{
  "clients": [
    {
      "id": "00000000-0000-4000-8000-000000000005",
      "name": "Hidden by selection",
      "projectCount": 1,
      "status": "active"
    },
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Synthetic visible client",
      "projectCount": 1,
      "status": "active"
    }
  ],
  "latestEvidenceDate": null,
  "projects": [
    {
      "cadence": null,
      "clientId": "00000000-0000-4000-8000-000000000005",
      "id": "00000000-0000-4000-8000-000000000006",
      "latestEvidenceDate": null,
      "name": "Hidden by selection",
      "status": "active"
    },
    {
      "cadence": null,
      "clientId": "33333333-3333-4333-8333-333333333333",
      "id": "11111111-1111-4111-8111-111111111111",
      "latestEvidenceDate": null,
      "name": "Synthetic visible project",
      "status": "active"
    }
  ],
  "teamType": null
}

Use IDs and versions from your own preceding responses. Replace the synthetic UUIDs, dates and names in these independent examples. Set SCOPEWORTH_API_BASE and SCOPEWORTH_API_KEY only on your server.

cURL

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/directory" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

JavaScript fetch

// Run on your server. API_BASE ends in /api/v1 (combined host) or /v1 (verified cell).
const response = await fetch(process.env.SCOPEWORTH_API_BASE + "/organizations/example-org/workspaces/example-workspace/directory", {
  method: "GET",
  headers: {
  "Authorization": `Bearer ${process.env.SCOPEWORTH_API_KEY}`
},
});
if (!response.ok) throw new Error(`ScopeWorth refused request: ${response.status}`);
const result = await response.json();

Python requests

import os, requests
headers = {"Authorization":"Bearer " + os.environ["SCOPEWORTH_API_KEY"]}
response = requests.request("GET", os.environ["SCOPEWORTH_API_BASE"] + "/organizations/example-org/workspaces/example-workspace/directory", headers=headers, timeout=30)
response.raise_for_status()
result = response.json()

For refusals, follow error recovery. A scope or plan badge is eligibility, not proof of authorization or available evidence. Read current directory IDs and versions before correcting a request. Keep an idempotency key for one unchanged mutation attempt; never blindly retry uncertain external work.

Run the snippet on your server. Save accessible clientId/projectId values from the response and verify their parent relationship. Slugs identify a namespace; UUIDs identify resources inside it. A 200 proves this authenticated read, not write permission. An empty directory means no accessible resources, not measured zero performance.

On 401 check key expiry/revocation; on 403 check scopes and current creator permissions; on 404 recheck the current namespace pair. Continue with clients/projects, imports, reports and error recovery.