Manage Workspaces | TutorFlow Agent Platform Docs

Internal management API. These endpoints are authenticated via TutorFlow admin auth in the current MVP, not via Platform API keys.

POST /v1/platform/workspaces

Create a new platform workspace.

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Display name for the workspace
`slug`	`string`	Yes	URL-safe identifier, must be unique
`email`	`string`	No	Contact email for the workspace
`rateLimitPerMinute`	`number`	No	Rate limit in requests per minute. Defaults to `1000`
`planCode`	`string`	No	Plan code to assign (e.g., `standard`), or `null` for no plan
`billingMode`	`string`	No	`internal_invoice` or `stripe_metered`. Defaults to `internal_invoice`
`stripeCustomerId`	`string`	No	Stripe customer ID for billing
`stripeSubscriptionId`	`string`	No	Stripe subscription backing metered billing
`stripeSubscriptionItemIdFast`	`string`	No	Stripe subscription item for the fast tier
`stripeSubscriptionItemIdStandard`	`string`	No	Stripe subscription item for the standard tier
`stripeSubscriptionItemIdAdvanced`	`string`	No	Stripe subscription item for the advanced tier

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My EdTech Company",
    "slug": "my-edtech",
    "email": "admin@myedtech.com",
    "planCode": null,
    "billingMode": "internal_invoice",
    "stripeCustomerId": "cus_test_123"
  }'

Response

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 0,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "stripeCustomerId": "cus_test_123",
  "stripeSubscriptionId": null,
  "stripeSubscriptionItemIdFast": null,
  "stripeSubscriptionItemIdStandard": null,
  "stripeSubscriptionItemIdAdvanced": null,
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Workspace unique identifier
`name`	`string`	Display name
`slug`	`string`	URL-safe identifier
`email`	`string \| null`	Contact email
`status`	`string`	`ACTIVE` or `SUSPENDED`
`creditBalance`	`number`	Current credit balance
`rateLimitPerMinute`	`number`	Rate limit in requests per minute
`planCode`	`string \| null`	Assigned plan code
`billingMode`	`string`	`internal_invoice` or `stripe_metered`
`stripeCustomerId`	`string \| null`	Stripe customer ID
`stripeSubscriptionId`	`string \| null`	Stripe subscription ID
`stripeSubscriptionItemIdFast`	`string \| null`	Stripe subscription item for fast tier
`stripeSubscriptionItemIdStandard`	`string \| null`	Stripe subscription item for standard tier
`stripeSubscriptionItemIdAdvanced`	`string \| null`	Stripe subscription item for advanced tier
`organizationId`	`string \| null`	Linked TutorFlow organization ID
`createdAt`	`string`	ISO 8601 creation timestamp
`updatedAt`	`string`	ISO 8601 last-updated timestamp

GET /v1/platform/workspaces

List all workspaces you have access to.

Example Request

curl https://api.tutorflow.io/v1/platform/workspaces \
  -H "Authorization: Bearer tf_platform_..."

Response

[
  {
    "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
    "name": "My EdTech Company",
    "slug": "my-edtech",
    "email": "admin@myedtech.com",
    "status": "ACTIVE",
    "creditBalance": 0,
    "rateLimitPerMinute": 1000,
    "planCode": null,
    "billingMode": "internal_invoice",
    "stripeCustomerId": "cus_test_123",
    "organizationId": null,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
]

GET /v1/platform/workspaces/:id

Get details of a specific workspace.

Example Request

curl https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID \
  -H "Authorization: Bearer tf_platform_..."

Response

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 0,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "stripeCustomerId": "cus_test_123",
  "stripeSubscriptionId": null,
  "stripeSubscriptionItemIdFast": null,
  "stripeSubscriptionItemIdStandard": null,
  "stripeSubscriptionItemIdAdvanced": null,
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

PATCH /v1/platform/workspaces/:id

Update workspace details. All fields are optional; only the fields you include will be updated.

Request Body

Field	Type	Required	Description
`name`	`string`	No	Updated display name
`email`	`string`	No	Updated contact email
`rateLimitPerMinute`	`number`	No	Rate limit in requests per minute
`planCode`	`string`	No	Plan code to assign
`billingMode`	`string`	No	`internal_invoice` or `stripe_metered`
`stripeCustomerId`	`string`	No	Stripe customer ID for invoicing or meter reporting
`stripeSubscriptionId`	`string`	No	Stripe subscription backing metered billing
`stripeSubscriptionItemIdFast`	`string`	No	Stripe subscription item for the fast tier
`stripeSubscriptionItemIdStandard`	`string`	No	Stripe subscription item for the standard tier
`stripeSubscriptionItemIdAdvanced`	`string`	No	Stripe subscription item for the advanced tier

Example Request

curl -X PATCH https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Company Name",
    "email": "new@email.com",
    "planCode": "standard",
    "billingMode": "stripe_metered",
    "stripeCustomerId": "cus_test_123",
    "stripeSubscriptionId": "sub_test_123",
    "stripeSubscriptionItemIdFast": "si_fast_123",
    "stripeSubscriptionItemIdStandard": "si_standard_123",
    "stripeSubscriptionItemIdAdvanced": "si_advanced_123"
  }'

Response

Returns the full updated workspace object.

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "Updated Company Name",
  "slug": "my-edtech",
  "email": "new@email.com",
  "status": "ACTIVE",
  "creditBalance": 0,
  "rateLimitPerMinute": 1000,
  "planCode": "standard",
  "billingMode": "stripe_metered",
  "stripeCustomerId": "cus_test_123",
  "stripeSubscriptionId": "sub_test_123",
  "stripeSubscriptionItemIdFast": "si_fast_123",
  "stripeSubscriptionItemIdStandard": "si_standard_123",
  "stripeSubscriptionItemIdAdvanced": "si_advanced_123",
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2026-03-29T09:00:00Z"
}

POST /v1/platform/workspaces/:id/credits

Add credits to a workspace's balance.

Credits are the internal billing ledger for the current MVP. Public pricing is exposed as per-evaluation pricing, while the backend uses credits to support included usage and future plan variations.

Request Body

Field	Type	Required	Description
`amount`	`number`	Yes	Number of credits to add (positive integer, minimum 1)
`reason`	`string`	No	Human-readable reason for the credit adjustment

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID/credits \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "reason": "Monthly credit top-up"
  }'

Response

Returns the full workspace object with the updated creditBalance.

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 1000,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2026-03-29T09:00:00Z"
}

POST /v1/platform/workspaces/:id/suspend

Suspend a workspace. All API keys will stop working.

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID/suspend \
  -H "Authorization: Bearer tf_platform_..."

Response

Returns the full workspace object with status set to SUSPENDED.

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "SUSPENDED",
  "creditBalance": 1000,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2026-03-29T09:30:00Z"
}

POST /v1/platform/workspaces/:id/activate

Reactivate a suspended workspace.

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID/activate \
  -H "Authorization: Bearer tf_platform_..."

Response

Returns the full workspace object with status set to ACTIVE.

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 1000,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "organizationId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2026-03-29T10:00:00Z"
}

POST /v1/platform/workspaces/from-organization

Create a platform workspace from an existing TutorFlow organization. This automatically links the new workspace to the organization.

Request Body

Field	Type	Required	Description
`organizationId`	`string`	Yes	The ID of the existing TutorFlow organization
`name`	`string`	Yes	Workspace name
`slug`	`string`	Yes	URL-safe slug
`email`	`string`	No	Contact email

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces/from-organization \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "existing-org-uuid",
    "name": "My EdTech Company",
    "slug": "my-edtech",
    "email": "admin@myedtech.com"
  }'

Response

Returns the full workspace object with the organization linked.

{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 0,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "stripeCustomerId": null,
  "stripeSubscriptionId": null,
  "stripeSubscriptionItemIdFast": null,
  "stripeSubscriptionItemIdStandard": null,
  "stripeSubscriptionItemIdAdvanced": null,
  "organizationId": "existing-org-uuid",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

POST /v1/platform/workspaces/:id/link

Link a platform workspace to an existing TutorFlow organization. This enables shared billing and unified management.

Request Body

Field	Type	Required	Description
`organizationId`	`string`	Yes	ID of the TutorFlow organization to link

Example Request

curl -X POST https://api.tutorflow.io/v1/platform/workspaces/WORKSPACE_ID/link \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "existing-org-uuid"
  }'

Note: organizationId here refers to the TutorFlow organization being linked to, not the workspace itself.

Response

Returns the full workspace object with the linked organizationId.

{
  "id": "b3f1a2c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "My EdTech Company",
  "slug": "my-edtech",
  "email": "admin@myedtech.com",
  "status": "ACTIVE",
  "creditBalance": 0,
  "rateLimitPerMinute": 1000,
  "planCode": null,
  "billingMode": "internal_invoice",
  "organizationId": "existing-org-uuid",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2026-03-29T10:00:00Z"
}