> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Split API usage across sub-accounts, departments, or clients for easy cost tracking and rebilling

## 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.

<CardGroup cols={3}>
  <Card title="Per-Client Billing" icon="file-invoice-dollar">
    Track exactly how many credits each of your clients consumes
  </Card>

  <Card title="Legal Entity Mapping" icon="building-columns">
    Associate each workspace with a legal name for invoicing
  </Card>

  <Card title="Usage Reporting API" icon="chart-column">
    Pull usage reports programmatically to automate rebilling
  </Card>
</CardGroup>

***

## How It Works

```mermaid theme={null}
flowchart LR
    A[Your Platform] -->|x-topograph-workspace-id: client-a| B[Topograph API]
    A -->|x-topograph-workspace-id: client-b| B
    A -->|no header = default| B
    B --> C[Usage tracked per workspace]
    C --> D[GET /v2/workspaces/usage]
    D --> E[Rebill each client]
```

<Steps>
  <Step title="Create workspaces for each client">
    Use `POST /v2/workspaces` to create a workspace with a name and legal entity name.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Pull usage reports">
    Call `GET /v2/workspaces/usage` to get a per-workspace breakdown of credits consumed, filterable by date range.
  </Step>

  <Step title="Rebill your clients">
    Use the usage report to generate invoices for each client based on their actual consumption.
  </Step>
</Steps>

***

## Managing Workspaces

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

### Create a Workspace

```bash theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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"
}
```

<Info>
  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.
</Info>

### List Workspaces

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY"
```

<Warning>
  You cannot delete the **default** workspace, or any workspace that has existing requests associated with it.
</Warning>

***

## Tagging Requests

Add the `x-topograph-workspace-id` header to any data retrieval or onboarding request:

```bash theme={null}
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"]
  }'
```

<Note>
  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`.
</Note>

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:

```json theme={null}
{
  "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](/guides/webhooks) notification for a completed request, the workspace is included in the payload:

```json theme={null}
{
  "request": {
    "requestId": "abc-123",
    "companyId": "443061841",
    "countryCode": "FR"
  },
  "workspace": {
    "name": "acme-paris",
    "legalName": "Acme Paris SAS"
  },
  "company": { ... }
}
```

<Tip>
  You can use the workspace info in webhook payloads to automatically route results to the correct client or trigger per-client processing pipelines.
</Tip>

***

## 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

```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
[
  {
    "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

```bash theme={null}
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

```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris" \
  -H "x-api-key: YOUR_API_KEY"
```

### Combine Filters

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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.

    ```python theme={null}
    # 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"]}
    )
    ```
  </Accordion>

  <Accordion title="Automated Monthly Rebilling">
    Set up a cron job to pull usage at the end of each month and generate invoices automatically.

    ```python theme={null}
    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")
    ```
  </Accordion>
</AccordionGroup>

***

## API Reference

| Endpoint                                                                           | Method | Description         |
| ---------------------------------------------------------------------------------- | ------ | ------------------- |
| [`/v2/workspaces`](/api-reference/workspaces/list-all-workspaces)                  | GET    | List all workspaces |
| [`/v2/workspaces`](/api-reference/workspaces/create-a-new-workspace)               | POST   | Create a workspace  |
| [`/v2/workspaces/{name}`](/api-reference/workspaces/update-a-workspace)            | PATCH  | Update a workspace  |
| [`/v2/workspaces/{name}`](/api-reference/workspaces/delete-a-workspace)            | DELETE | Delete a workspace  |
| [`/v2/workspaces/usage`](/api-reference/workspaces/get-usage-report-per-workspace) | GET    | Get usage report    |

<Tip>
  The `x-topograph-workspace-id` header is supported on [/v2/company](/api-reference/data/get-company-data-and-documents) (all modes, including `mode: "onboarding"`). The legacy `/v2/onboarding` route also accepts it.
</Tip>