Update a Browser Profile

PATCH/v1/browser/profiles/{profile_id}

The name is Spider-owned display metadata, updated atomically with If-Match and without renaming the provider Profile. A name-only update returns 200. Proxy changes register durable asynchronous work; the previous binding remains authoritative until verification. Concurrent requests with the same version have at most one winner; a stale version returns 412.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X PATCH "https://kieapi.com/v1/browser/profiles/{profile_id}" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'If-Match: <value>' \
  -H "Content-Type: application/json" \
  -d '{}'

Authentication

BearerAuth

Parameters

profile_id path · string required
If-Match header · string required: Browser Profile version ETag returned by create, get, clone, or patch. List responses expose the same numeric version in each Profile resource.

Request body required

application/json

BrowserProfileUpdateRequest

proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
name string | null
proxy_id string | null: Set null to detach the Proxy; omit to preserve the current binding.

Responses

200 Browser Profile metadata updated synchronously.

application/json

BrowserProfileResponse

profile BrowserProfile required

202 Proxy update accepted for asynchronous two-phase verification.

application/json

BrowserProfileResponse

profile BrowserProfile required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

404 Browser profile was not found or is not visible to this workspace.

application/json

PublicErrorResponse

error PublicError required

409 Browser resource state, idempotency, Proxy authority, or controller ownership conflicts with this request.

application/json

PublicErrorResponse

error PublicError required

412 If-Match does not match the current Browser Profile version.

application/json

PublicErrorResponse

error PublicError required

422 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

428 If-Match is required for this Browser Profile mutation.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

BrowserProfileUpdateRequest

object

proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
name string | null
proxy_id string | null: Set null to detach the Proxy; omit to preserve the current binding.

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "proxy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProxySelection"
        },
        {
          "type": "null"
        }
      ],
      "description": "Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128
    },
    "proxy_id": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 128,
      "description": "Set null to detach the Proxy; omit to preserve the current binding."
    }
  }
}

BrowserProxySelection

object

Exactly one mode: direct has no extra fields; system_dynamic requires a published country and optional published sticky_minutes; account_static/custom_proxy require resource_id and may specify required_country. Credentials are never accepted.

mode string required: Allowed: "direct", "system_dynamic", "account_static", "custom_proxy"
country string or null: Default: null
sticky_minutes integer or null: Default: null
resource_id string or null: Default: null
required_country string or null: Default: null

Complete schema

{
  "additionalProperties": false,
  "description": "Exactly one mode: direct has no extra fields; system_dynamic requires a published country and optional published sticky_minutes; account_static/custom_proxy require resource_id and may specify required_country. Credentials are never accepted.",
  "properties": {
    "mode": {
      "enum": [
        "direct",
        "system_dynamic",
        "account_static",
        "custom_proxy"
      ],
      "title": "Mode",
      "type": "string"
    },
    "country": {
      "anyOf": [
        {
          "maxLength": 2,
          "minLength": 2,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Country"
    },
    "sticky_minutes": {
      "anyOf": [
        {
          "enum": [
            5,
            10,
            30
          ],
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sticky Minutes"
    },
    "resource_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Id"
    },
    "required_country": {
      "anyOf": [
        {
          "maxLength": 2,
          "minLength": 2,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Required Country"
    }
  },
  "required": [
    "mode"
  ],
  "type": "object"
}

BrowserProfileResponse

object

profile BrowserProfile required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "profile"
  ],
  "properties": {
    "profile": {
      "$ref": "#/components/schemas/BrowserProfile"
    }
  }
}

BrowserProfile

object

proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
id string required
name string required
created_at string (date-time) required
updated_at string (date-time) required
last_used_at string | null (date-time) required
status string required: Allowed: "creating", "ready", "in_use", "saving", "create_failed", "updating", "update_failed", "save_failed", "deleting", "deleted", "delete_failed", "error"
device_profile string required: Allowed: "auto", "windows", "macos", "linux", "android", "ios"
proxy_id string | null required
version integer required
failure BrowserProfileFailure or null required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "name",
    "status",
    "device_profile",
    "proxy_id",
    "version",
    "created_at",
    "updated_at",
    "last_used_at",
    "failure"
  ],
  "properties": {
    "proxy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProxySelection"
        },
        {
          "type": "null"
        }
      ],
      "description": "Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy."
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_used_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": [
        "creating",
        "ready",
        "in_use",
        "saving",
        "create_failed",
        "updating",
        "update_failed",
        "save_failed",
        "deleting",
        "deleted",
        "delete_failed",
        "error"
      ]
    },
    "device_profile": {
      "type": "string",
      "enum": [
        "auto",
        "windows",
        "macos",
        "linux",
        "android",
        "ios"
      ]
    },
    "proxy_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "version": {
      "type": "integer",
      "minimum": 1
    },
    "failure": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProfileFailure"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

BrowserProfileFailure

object

code string required: Allowed: "profile_create_failed", "profile_update_failed", "profile_save_failed", "profile_delete_failed", "profile_runtime_unavailable"
occurred_at string (date-time) required
recovered_at string | null (date-time) required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "occurred_at",
    "recovered_at"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "profile_create_failed",
        "profile_update_failed",
        "profile_save_failed",
        "profile_delete_failed",
        "profile_runtime_unavailable"
      ]
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "recovered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}