Skip to content
SupaCloud Docs
Select themeSelect language

put_api_management_v1_workspaces_slug_state

PUT
/api/management/v1/workspaces/{slug}/state

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
ai_credentials
Array<object>
object
key
required
string
label
string | null
provider
required
string
budget
One of:
null
capabilities
One of:
null
git_credentials
Array<object>
object
auth_type
required
string
credential_data
required
string
git_provider
string | null
label
required
string
invites
Array<object>
object
email
required
string
role
required
string
mailbox_credentials
Array<object>
object
allowed_login_providers
Array<string>
email
required
string
imap_host
required
string
imap_port
integer format: int32
label
required
string
password_secret_ref
required
string
provider
string | null
use_tls
boolean
username
required
string
members
Array<object>
object
admin
boolean
approved
boolean
display_name
string | null
email
required
string
role
required
string
oauth_credentials
Array<object>
object
access_token
required
string
account_email
string | null
expires_at
string | null format: date-time
id_token
string | null
provider
required
string
refresh_token
required
string
projects
Array<object>
object
auto_developer_agent_type
string | null
auto_developer_enabled

#708 X2b — the PR-flow arming fields the management apply honors. auto_developer_enabled arms the pr_review automation arm; auto_developer_agent_type stamps its source_filter.harness. The legacy auto_developer_prompt/_modes/_draft_first/… spec fields were removed with the dropped projects.auto_developer_* columns.

boolean | null
auto_issue_debate_enabled

#708 M1/X5 — DEPRECATED. The standalone issue-debate lane was retired (#708 B3/X5): the council capability is the per-stage council flag, and the auto_issue_debate_* columns were dropped (migration 302). This field is KEPT only so a stale IaC manifest that tries to ARM the lane fails LOUDLY: an apply that sets it true is REJECTED with a 422 (see apply_project) sourced from THIS request field. false / absent stays accepted for backward-compatible manifests. The other auto_issue_debate_* spec fields were removed.

boolean | null
closeout_config
One of:
null
git_credential_label
string | null
git_default_branch
string | null
git_provider
string | null
git_repo_url
string | null
key
required
string
name
required
string
resources

#918 — workspace resources (postgresql / seafile_webdav / telegram_bot / custom / …) with write-only secrets. Additive like every list here: entries absent from the payload are never deleted server-side.

Array<object>

#918 — one workspace resource in the desired state. Mirrors the resource create/update API surface; the secret is WRITE-ONLY (never echoed back; the apply result carries a fingerprint at most).

object
config
kind
required

Resource kind (closed catalogue + custom, validated by the resources service). Immutable on update, like the user-facing API.

string
name
required

Resource name — the upsert identity within the workspace (bindings and scripts reference resources by name).

string
secret

Write-only secret. Absent/null → leave the stored secret alone (additive contract — IaC can re-apply without re-supplying secrets). A string is stored as-is; a JSON object (#914 custom structured secrets) is stored as its canonical JSON serialisation.

schedules
Array<object>
object
agent_type
required
string
cadence
required

once | daily | weekly | monthly | interval.

string
config
interval_minutes

#908 — the step width of an interval cadence in minutes (5–1440). Required iff cadence = 'interval'; rejected on any other cadence.

integer | null format: int32
>= 5 <= 1440
key
required
string
next_run_at
required
string format: date-time
project_key
string | null
prompt
required
string
timezone
string | null
title
required
string
task_scopes
One of:
null
tasks
Array<object>
object
agent_type
required
string
closeout
One of:
null
config
object
key
additional properties
issue_id

Optional issue-link intent. When BOTH issue_id and issue_url are present, the launch path links the task to that existing issue by merging link_issue_id/link_issue_url into config via the typed services::tasks::IssueLinkConfig builder (ADR 0032, Issue #248). Either field alone is a no-op, keeping legacy callers that only send config unchanged.

string | null
issue_url
string | null
key
required
string
project_key
string | null
prompt
required
string
title
required
string
variables
Array<object>
object
is_secret
boolean
key
required
string
project_key
string | null
value
required
string
workflow_schedules

#918 — workflow schedules: one spec creates/updates the schedule row AND its linked schedule-kind trigger on the workflow.

Array<object>

#918 — one workflow schedule in the desired state: upserts the schedule row (cadence incl. interval per #908) and ensures the linked schedule-kind trigger on the workflow exists and is enabled.

object
cadence
required

once | daily | weekly | monthly | interval.

string
interval_minutes

Required iff cadence = 'interval' (5–1440 minutes, #908).

integer | null format: int32
>= 5 <= 1440
key
required

Stable reconcile identity (task_schedules.management_key).

string
next_run_at
required

First-fire hint — preserved across re-applies unless the cadence changes (same semantics as managed task schedules).

string format: date-time
project_key
string | null
timezone
string | null
workflow
required

The workflow’s name (repo-sync slug / display name).

string
workflow_templates

#987 Stage B — workflows MATERIALIZED FROM A SHIPPED TEMPLATE, upserted per (project, key) via the workflows.management_key column (migration 337). The blocks above can only RESOLVE an existing workflow by name; this one CREATES it, which is what makes a mail / scan workspace provisionable in one declarative request.

Array<object>

#987 Stage B — one workflow MATERIALIZED FROM A SHIPPED TEMPLATE in the desired state.

This is the block that makes a mail / scan workspace provisionable through the product path: before it, the state-apply could only RESOLVE an already-existing workflow by name (workflow_triggers / workflow_schedules), never create one, so an operator had to hand-compose the graph in the builder or via repo-sync first. Reconciled per (project, key) on workflows.management_key (migration 337) — deliberately NOT on the workflow NAME, which cannot survive a rename and is ambiguous across a workspace.

Additive like every list in the document: an entry that disappears from the payload is never deleted server-side, and a re-apply of an entry whose workflow already exists is a no-op reporting changed: false (the graph belongs to the user once it is materialized — the apply never overwrites their edits).

object
config

The template’s ${{ config.* }} substitution map, plus the per-slug materialization parameters (e.g. mail_intake’s mailbox_resource_id). Missing keys fall back to the template’s registry defaults.

A value of the form ${{ resources.<name>.id }} is resolved against the resources applied EARLIER IN THE SAME REQUEST, so an operator binds a mailbox or a document library by NAME and never pastes a UUID into a manifest. An unknown resource name fails the item loudly.

object
key
additional properties
string
key
required

Stable reconcile identity within the project (workflows.management_key).

string
name

Optional display name for the materialized workflow. Absent → the template’s own name:. Purely cosmetic: the reconcile identity is key, so renaming here never orphans the row.

string | null
project_key

Project that owns the workflow (ManagementProjectSpec.key). Absent → the workspace’s single project; ambiguous when the workspace has several.

string | null
template
required

The shipped template slug to materialize (mail_intake, scan_intake, autodev, …). An unknown slug fails the apply LOUDLY with a 404 rather than materializing nothing.

string
workflow_triggers

#918 — workflow triggers, upserted per (workflow, key) via the management_key column (migration 325). repo-sync deliberately never applies triggers: on pull — this is the declarative path.

Array<object>

#918 — one workflow trigger in the desired state, upserted per (workflow, key) (migration 325 management_key).

object
config
enabled
boolean
key
required

Stable reconcile identity within the workflow.

string
kind
required

Trigger kind (webhook, schedule, telegram, …) — validated by the triggers service.

string
project_key

Project that owns the workflow (ManagementProjectSpec.key). Absent → the workflow is looked up across the workspace’s landing project.

string | null
workflow
required

The workflow’s name (repo-sync slug / display name).

string
workspace
required
object
name
required
string
owner_email
string | null

Responses

Section titled “Responses”

200

Section titled “200”

Workspace desired state applied

Media typeapplication/json
object
changed
required
boolean
results
required
Array<object>
object
changed
required
boolean
fingerprint
string | null
id
string | null format: uuid
key
required
string
resource_type
required
string
workspace_id
required
string format: uuid
Examplegenerated
{
  "changed": true,
  "results": [
    {
      "changed": true,
      "fingerprint": "example",
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "key": "example",
      "resource_type": "example"
    }
  ],
  "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}