Skip to main content

​
Overview

Workspaces let you tag every API request with a sub-account identifier, so you can track and rebill usage per client, department, or entity. This is especially useful for resellers, multi-entity organizations, and platforms that need granular cost attribution. Each workspace has a legal name tied to it — perfect for invoicing and compliance.

Per-Client Billing

Track exactly how many credits each of your clients consumes

Legal Entity Mapping

Associate each workspace with a legal name for invoicing

Usage Reporting API

Pull usage reports programmatically to automate rebilling

​
How It Works

1

Create workspaces for each client

Use POST /v2/workspaces to create a workspace with a name and legal entity name.
2

Tag requests with the x-topograph-workspace-id header

Pass x-topograph-workspace-id: workspace-name on every API call. If omitted, requests go to the default workspace.
3

Pull usage reports

Call GET /v2/workspaces/usage to get a per-workspace breakdown of credits consumed, filterable by date range.
4

Rebill your clients

Use the usage report to generate invoices for each client based on their actual consumption.

​
Managing Workspaces

Every account starts with a default workspace. You can create additional workspaces — one per client, department, or legal entity.

​
Create a Workspace

curl -X POST "https://api.topograph.co/v2/workspaces" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-paris",
    "legalName": "Acme Paris SAS"
  }'
Response
{
  "id": "ws-abc123",
  "name": "acme-paris",
  "legalName": "Acme Paris SAS",
  "isDefault": false,
  "createdAt": "2026-03-09T14:00:00.000Z",
  "updatedAt": "2026-03-09T14:00:00.000Z"
}
Workspace names must be alphanumeric with hyphens and underscores only (max 64 characters). The name default is reserved.

​
List Workspaces

curl "https://api.topograph.co/v2/workspaces" \
  -H "x-api-key: YOUR_API_KEY"

​
Update a Workspace

Update the legal name associated with a workspace: 
curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legalName": "Acme Paris SAS (updated)"}'

​
Delete a Workspace

curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY"
You cannot delete the default workspace, or any workspace that has existing requests associated with it.

​
Tagging Requests

Add the x-topograph-workspace-id header to any data retrieval or onboarding request: 
curl -X POST "https://api.topograph.co/v2/company" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-topograph-workspace-id: acme-paris" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "443061841",
    "countryCode": "FR",
    "dataPoints": ["companyProfile"]
  }'
If the x-topograph-workspace-id header is omitted, the request is automatically tagged to the default workspace. If the workspace name doesn’t exist, the API returns a 400 Bad Request.
The workspace tag is propagated to all billing events generated by the request, so every credit consumed is attributed to the correct workspace.

​
Workspace in API Responses

The workspace is returned in every API response inside the request object: 
{
  "request": {
    "requestId": "abc-123",
    "companyId": "443061841",
    "countryCode": "FR",
    "workspace": {
      "name": "acme-paris",
      "legalName": "Acme Paris SAS"
    },
    "dataStatus": { ... }
  },
  "company": { ... }
}

​
Workspace in Webhooks

When you receive a webhook notification for a completed request, the workspace is included in the payload: 
{
  "request": {
    "requestId": "abc-123",
    "companyId": "443061841",
    "countryCode": "FR"
  },
  "workspace": {
    "name": "acme-paris",
    "legalName": "Acme Paris SAS"
  },
  "company": { ... }
}
You can use the workspace info in webhook payloads to automatically route results to the correct client or trigger per-client processing pipelines.

​
Usage Reporting

The usage report endpoint gives you a per-workspace breakdown of all credits consumed — exactly what you need to rebill your clients.

​
Get Full Report

curl "https://api.topograph.co/v2/workspaces/usage" \
  -H "x-api-key: YOUR_API_KEY"
Response
[
  {
    "workspace": {
      "name": "default",
      "legalName": "Your Company Inc.",
      "isDefault": true
    },
    "totalCreditsUsed": 42.5,
    "totalRequests": 85,
    "breakdown": [
      { "sku": "fra-company-data", "count": 50, "totalCredits": 25.0 },
      { "sku": "deu-company-data", "count": 35, "totalCredits": 17.5 }
    ]
  },
  {
    "workspace": {
      "name": "acme-paris",
      "legalName": "Acme Paris SAS",
      "isDefault": false
    },
    "totalCreditsUsed": 15.0,
    "totalRequests": 30,
    "breakdown": [
      { "sku": "fra-company-data", "count": 30, "totalCredits": 15.0 }
    ]
  }
]

​
Filter by Date Range

curl "https://api.topograph.co/v2/workspaces/usage?startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-api-key: YOUR_API_KEY"

​
Filter by Workspace

curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris" \
  -H "x-api-key: YOUR_API_KEY"

​
Combine Filters

curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris&startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-api-key: YOUR_API_KEY"

​
Use Cases

You resell Topograph to your own clients. Create one workspace per client, tag all their requests, and pull monthly usage reports to generate invoices.
Workspace: client-alpha    → 120 credits → Invoice €120
Workspace: client-beta     → 45 credits  → Invoice €45
Workspace: client-gamma    → 200 credits → Invoice €200
Your company has multiple legal entities or branches. Each entity gets its own workspace with the correct legal name, so you can allocate costs internally.
Workspace: default         → HQ (Paris)     → 500 credits
Workspace: london-office   → London Ltd      → 200 credits
Workspace: berlin-office   → Berlin GmbH     → 150 credits
You build a platform where your users trigger Topograph requests. Tag each request with the user’s workspace to track per-tenant consumption and enforce usage limits.
# In your platform backend
response = requests.post(
    "https://api.topograph.co/v2/company",
    headers={
        "x-api-key": API_KEY,
        "x-topograph-workspace-id": tenant.workspace_name,
    },
    json={"id": company_id, "countryCode": "FR", "dataPoints": ["companyProfile"]}
)
Set up a cron job to pull usage at the end of each month and generate invoices automatically.
import requests
from datetime import datetime

# First day of current month
start = datetime.now().replace(day=1).strftime("%Y-%m-%d")
end = datetime.now().strftime("%Y-%m-%d")

usage = requests.get(
    f"https://api.topograph.co/v2/workspaces/usage?startDate={start}&endDate={end}",
    headers={"x-api-key": API_KEY}
).json()

for report in usage:
    ws = report["workspace"]
    credits = report["totalCreditsUsed"]
    print(f"Invoice {ws['legalName']}: {credits} credits")

​
API Reference

EndpointMethodDescription
/v2/workspacesGETList all workspaces
/v2/workspacesPOSTCreate a workspace
/v2/workspaces/{name}PATCHUpdate a workspace
/v2/workspaces/{name}DELETEDelete a workspace
/v2/workspaces/usageGETGet usage report
The x-topograph-workspace-id header is supported on the /v2/company and /v2/onboarding endpoints.