Workspaces

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

Create workspaces for each client

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

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.

Pull usage reports

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

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": "253299d1-e8d0-4268-945b-f175f98bc114",
  "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. Use the workspace name in request headers and workspace URLs; the UUID id is returned for reference.

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": ["company", "legalRepresentatives"]
  }'

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": "example-company-data", "count": 50, "totalCredits": 25.0 },
      { "sku": "example-document", "count": 35, "totalCredits": 17.5 }
    ]
  },
  {
    "workspace": {
      "name": "acme-paris",
      "legalName": "Acme Paris SAS",
      "isDefault": false
    },
    "totalCreditsUsed": 15.0,
    "totalRequests": 30,
    "breakdown": [
      { "sku": "example-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

Resellers / Channel Partners

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 -> client invoice
Workspace: client-beta     -> 45 credits  -> client invoice
Workspace: client-gamma    -> 200 credits -> client invoice

Multi-Entity Organizations

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

Platform / SaaS Integration

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": ["company", "legalRepresentatives"]}
)

Automated Monthly Rebilling

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

Endpoint	Method	Description
`/v2/workspaces`	GET	List all workspaces
`/v2/workspaces`	POST	Create a workspace
`/v2/workspaces/{name}`	PATCH	Update a workspace
`/v2/workspaces/{name}`	DELETE	Delete a workspace
`/v2/workspaces/usage`	GET	Get usage report

The x-topograph-workspace-id header is supported on /v2/company (all modes, including mode: "onboarding"). The legacy /v2/onboarding route also accepts it.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Overview

Per-Client Billing

Legal Entity Mapping

Usage Reporting API

How It Works

Managing Workspaces

Create a Workspace

List Workspaces

Update a Workspace

Delete a Workspace

Tagging Requests

Workspace in API Responses

Workspace in Webhooks

Usage Reporting

Get Full Report

Filter by Date Range

Filter by Workspace

Combine Filters

Use Cases

API Reference

​Overview

Per-Client Billing

Legal Entity Mapping

Usage Reporting API

​How It Works

​Managing Workspaces

​Create a Workspace

​List Workspaces

​Update a Workspace

​Delete a Workspace

​Tagging Requests

​Workspace in API Responses

​Workspace in Webhooks

​Usage Reporting

​Get Full Report

​Filter by Date Range

​Filter by Workspace

​Combine Filters

​Use Cases

​API Reference

Overview

How It Works

Managing Workspaces

Create a Workspace

List Workspaces

Update a Workspace

Delete a Workspace

Tagging Requests

Workspace in API Responses

Workspace in Webhooks

Usage Reporting

Get Full Report

Filter by Date Range

Filter by Workspace

Combine Filters

Use Cases

API Reference