Skip to content
Hyperresearch docs

Update a workspace

PATCH
/v1/workspaces/{id}
curl --request PATCH \
  --url https://api.hyperresearch.ai/v1/workspaces/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "settings": { "fetch": { "rung_max": "L0", "max_html_bytes": 1, "max_pdf_bytes": 1, "allow_domains": [ "example" ], "deny_domains": [ "example" ] }, "robots": "strict", "clarify_default": "ask", "provider_exclusions": [ "example" ], "retention": { "raw_days": 1, "assets_days": 1 }, "reuse": { "default": "all", "max_age_days": 1 } } }'

Rename a workspace or change its settings. settings is merged into the stored settings, not replaced; keys you do not send keep their values. Owner/admin only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
id
required
string
>= 3 characters <= 64 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
string
>= 1 characters <= 120 characters
settings
object
fetch
object
rung_max
string
Allowed values: L0 L1 L2 L3 L4
max_html_bytes
integer
>= 1024 <= 50000000
max_pdf_bytes
integer
>= 1024 <= 67108864
allow_domains
Array<string>
<= 200 items
deny_domains
Array<string>
<= 200 items
robots
string
Allowed values: strict standard permissive
clarify_default

What every run in this workspace does about an ambiguous question, unless the request says otherwise: ask interviews the customer before anything is reserved, auto proceeds immediately on the stated assumptions and names them in the report, off skips the assessment entirely. Unset, the channel decides — ask from the console, auto from an API key, the CLI or MCP.

string
Allowed values: ask auto off
provider_exclusions
Array<string>
<= 32 items
retention
object
raw_days
integer
<= 3650
assets_days
integer
<= 3650
reuse
object
default
Any of:
boolean
max_age_days
integer
<= 3650

Responses

Section titled “ Responses ”

200

Section titled “200”

Updated

Media typeapplication/json
object
id
required
string
name
required
string
display_name
required

What to show a customer where the workspace is named. The workspace name, or “Untitled workspace” when it has none — never the id.

string
display_id
required

The id as a screen shows it: the prefix, an ellipsis and the last characters, the same treatment #/keys gives a key id. Support quotes an id by copying id, never by reading it off the page.

string
settings
required
object
fetch
object
rung_max
string
Allowed values: L0 L1 L2 L3 L4
max_html_bytes
integer
>= 1024 <= 50000000
max_pdf_bytes
integer
>= 1024 <= 67108864
allow_domains
Array<string>
<= 200 items
deny_domains
Array<string>
<= 200 items
robots
string
Allowed values: strict standard permissive
clarify_default

What every run in this workspace does about an ambiguous question, unless the request says otherwise: ask interviews the customer before anything is reserved, auto proceeds immediately on the stated assumptions and names them in the report, off skips the assessment entirely. Unset, the channel decides — ask from the console, auto from an API key, the CLI or MCP.

string
Allowed values: ask auto off
provider_exclusions
Array<string>
<= 32 items
retention
object
raw_days
integer
<= 3650
assets_days
integer
<= 3650
reuse
object
default
Any of:
boolean
max_age_days
integer
<= 3650
display_robots
required

The workspace robots handling as a sentence, beside the wire value (E2E6-12). #/settings rendered the bare enum — strict / standard / permissive — as the options of a select whose neighbour reads “Basic — the page as served”. The value is unchanged and is still what PATCH takes; this is what to show. The full option list is GET /v1/workspaces/robots-modes.

object
value
required
string
Allowed values: strict standard permissive
label
required
string
description
required
string
vault_bytes
required
integer
status
required
string
Allowed values: active deleting deleted
created_at
required
string
updated_at
required
string
Example
{
  "id": "ws_01J9ZQ7V6H0000000000000000",
  "display_id": "ws…GSB5GJ7",
  "settings": {
    "fetch": {
      "rung_max": "L0"
    },
    "robots": "strict",
    "clarify_default": "ask",
    "reuse": {
      "default": "all"
    }
  },
  "display_robots": {
    "value": "strict"
  },
  "status": "active"
}

Headers

Section titled “Headers”
RateLimit-Policy
string
Example
"reads";q=60;w=60

The quota policy this request was counted against (draft-ietf-httpapi-ratelimit-headers): "<bucket>";q=<requests>;w=<window seconds>, e.g. "reads";q=60;w=60. Buckets: reads 60/min, status 600/min, creates 10/min, writes 20/min per credential; public 300/min per network on keyless routes.

RateLimit
string
Example
"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit
integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining
integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset
integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket
string

Which bucket counted the request: reads, status, creates, writes or public.

400

Section titled “400”

Invalid request

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

401

Section titled “401”

Authentication failed

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

403

Section titled “403”

Insufficient scope or plan

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

404

Section titled “404”

Not found

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

429

Section titled “429”

Rate limited or over quota

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying. Always present on a 429.

RateLimit-Policy
string
Example
"reads";q=60;w=60

The quota policy this request was counted against (draft-ietf-httpapi-ratelimit-headers): "<bucket>";q=<requests>;w=<window seconds>, e.g. "reads";q=60;w=60. Buckets: reads 60/min, status 600/min, creates 10/min, writes 20/min per credential; public 300/min per network on keyless routes.

RateLimit
string
Example
"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit
integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining
integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset
integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket
string

Which bucket counted the request: reads, status, creates, writes or public.

500

Section titled “500”

Internal error

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal
code
required
string
Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error
message
required
string
param
string
retry_after
integer
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}