Workspaces

A workspace API key is scoped to one workspace. Use GET /v1/workspace for metadata plus embedded usage, or GET /v1/workspace/usage for usage only. Grant balances and billing overrides are applied server-side — responses only include used, limit, and remaining per service. Create keys in the dashboard (Workspace → Workspace keys).

Retrieve workspaceGET/v1/workspacechevron_right
Retrieve workspace usageGET/v1/workspace/usagechevron_right

The Workspace object

workspaceIdstring: Stable workspace identifier (wsp_…).
namestring: Display name.
descriptionstring: Optional description (may be an empty string).
planstring: Billing plan: free or enterprise.
usageobject: Monthly usage per billable service (see Usage object).

{
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "Acme Media",
  "description": "Production transcripts",
  "plan": "free",
  "usage": {
    "plan": "free",
    "resetsAt": "2026-06-30T21:54:53.299Z",
    "services": [
      { "service": "transcription", "used": 5, "limit": 10, "remaining": 5 },
      { "service": "indexer", "used": 1, "limit": 100, "remaining": 99 },
      { "service": "ai_search", "used": 0, "limit": 1000, "remaining": 1000 },
      { "service": "clip_generation", "used": 0, "limit": 1000, "remaining": 1000 },
      { "service": "thumbnail", "used": 3, "limit": 100, "remaining": 97 },
      { "service": "metadata", "used": 1, "limit": 100, "remaining": 99 },
      { "service": "summarization", "used": 1, "limit": 50, "remaining": 49 }
    ]
  }
}

Usage object

planstring: Billing plan for this workspace.
resetsAtstring: UTC ISO instant when monthly allowances reset.
servicesarray: One entry per billable service.
services[].servicestring: transcription, indexer, ai_search, clip_generation, thumbnail, metadata, or summarization.
services[].usednumber: Credits consumed this billing period.
services[].limitnumber | null: Monthly cap. null = unlimited (enterprise).
services[].remainingnumber | null: Credits still available (includes any bonus capacity; not itemized). null when unlimited.

{
  "plan": "free",
  "resetsAt": "2026-06-30T21:54:53.299Z",
  "services": [
    { "service": "transcription", "used": 5, "limit": 10, "remaining": 5 },
    { "service": "indexer", "used": 1, "limit": 100, "remaining": 99 },
    { "service": "ai_search", "used": 0, "limit": 1000, "remaining": 1000 },
    { "service": "clip_generation", "used": 0, "limit": 1000, "remaining": 1000 },
    { "service": "thumbnail", "used": 3, "limit": 100, "remaining": 97 },
    { "service": "metadata", "used": 1, "limit": 100, "remaining": 99 },
    { "service": "summarization", "used": 1, "limit": 50, "remaining": 49 }
  ]
}

Retrieve workspace

GET/v1/workspace

Returns workspace metadata and the embedded usage object for quota checks before jobs or catalog searches.

Requires permission

workspace:read

Authenticate with Authorization: Bearer sk_wsp_…. No X-Workspace-Id header. Project API keys cannot call this route.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/workspace" \
  -H "Authorization: Bearer sk_wsp_..."

{
  "data": {
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "Acme Media",
  "description": "Production transcripts",
  "plan": "free",
  "usage": {
    "plan": "free",
    "resetsAt": "2026-06-30T21:54:53.299Z",
    "services": [
      { "service": "transcription", "used": 5, "limit": 10, "remaining": 5 },
      { "service": "indexer", "used": 1, "limit": 100, "remaining": 99 },
      { "service": "ai_search", "used": 0, "limit": 1000, "remaining": 1000 },
      { "service": "clip_generation", "used": 0, "limit": 1000, "remaining": 1000 },
      { "service": "thumbnail", "used": 3, "limit": 100, "remaining": 97 },
      { "service": "metadata", "used": 1, "limit": 100, "remaining": 99 },
      { "service": "summarization", "used": 1, "limit": 50, "remaining": 49 }
    ]
  }
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Retrieve workspace usage

GET/v1/workspace/usage

Returns only the usage object — same shape as the usage field on GET /v1/workspace. Use when you do not need workspace name or description.

Requires permission

workspace:read

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/workspace/usage" \
  -H "Authorization: Bearer sk_wsp_..."

{
  "data": {
  "plan": "free",
  "resetsAt": "2026-06-30T21:54:53.299Z",
  "services": [
    { "service": "transcription", "used": 5, "limit": 10, "remaining": 5 },
    { "service": "indexer", "used": 1, "limit": 100, "remaining": 99 },
    { "service": "ai_search", "used": 0, "limit": 1000, "remaining": 1000 },
    { "service": "clip_generation", "used": 0, "limit": 1000, "remaining": 1000 },
    { "service": "thumbnail", "used": 3, "limit": 100, "remaining": 97 },
    { "service": "metadata", "used": 1, "limit": 100, "remaining": 99 },
    { "service": "summarization", "used": 1, "limit": 50, "remaining": 49 }
  ]
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}