User Organization Partial Update

PATCH

https://api.respan.ai/user/organization/:unique_organization_id/

PATCH

/user/organization/:unique_organization_id/

$ curl -X PATCH https://api.respan.ai/user/organization/unique_organization_id/ \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

200Updated

1 {
2   "id": 1,
3   "is_blocked": true,
4   "onboarding_method": "gateway",
5   "name": "string",
6   "status": "active",
7   "stripe_customer_id": "string",
8   "gateway_onboarding_completed_at": "2024-01-15T09:30:00Z",
9   "tracing_onboarding_completed_at": "2024-01-15T09:30:00Z",
10   "llm_gateway_markup_rate": 1.1,
11   "company_organization": 1,
12   "users": [
13     1
14   ],
15   "disabled_span_behaviors": [
16     "string"
17   ],
18   "warnings_settings": {
19     "fallback": true,
20     "retry": true,
21     "invalid_json": true,
22     "stream_timeout": true,
23     "empty_response": true,
24     "using_keywordsai_credentials": true
25   },
26   "custom_property_index_mapping": {},
27   "created_at": "2024-01-15T09:30:00Z",
28   "first_api_call_at": "2024-01-15T09:30:00Z",
29   "last_api_call_at": "2024-01-15T09:30:00Z",
30   "logo": "string",
31   "notes": "string",
32   "digest_email_inboxes": [
33     "string"
34   ],
35   "organization_size": 1,
36   "product_use_cases": [
37     "string"
38   ],
39   "prioritize_objectives": [
40     "string"
41   ],
42   "unique_organization_id": "string",
43   "budget_goal": "string",
44   "monthly_spending": 1.1,
45   "preset_models": [
46     "string"
47   ],
48   "preset_option": "string",
49   "dynamic_routing_enabled": true,
50   "fallback_model_enabled": true,
51   "fallback_models": [
52     "string"
53   ],
54   "system_fallback_enabled": true,
55   "alerts_enabled": true,
56   "disable_log": true,
57   "has_api_call": true,
58   "onboarded": true,
59   "has_api_call_with_non_default_key": true,
60   "onboarding_key": "string",
61   "curr_onboarding_step": 1,
62   "onboarding_start": "2024-01-15T09:30:00Z",
63   "onboarding_end": "2024-01-15T09:30:00Z",
64   "enable_cache": true,
65   "archive_duration": 1,
66   "cache_saved_cost": 1.1,
67   "cache_hit_count": 1,
68   "cache_hit_tokens": 1,
69   "omit_log_when_cache_hit": true,
70   "cache_saved_time": 1.1,
71   "last_cache_aggregations_update": "2024-01-15T09:30:00Z",
72   "classification_percentage": 1.1,
73   "use_custom_credentials": true,
74   "default_customer_user_budget": 1.1,
75   "credit_low_balance_threshold": 1.1,
76   "credit_auto_top_off_threshold": 1.1,
77   "credit_auto_top_off_amount": 1.1,
78   "is_auto_top_off_enabled": true,
79   "metadata_keys": [
80     "string"
81   ],
82   "custom_models": [
83     "string"
84   ],
85   "spend_cap": 1.1,
86   "spend_cap_warning_threshold": 1.1,
87   "budget_duration": "daily",
88   "use_keywordsai_credentials": true,
89   "rate_limit": 1.1,
90   "customer_user_rate_limit": 1.1,
91   "retry_enabled": true,
92   "retry_after": 1.1,
93   "num_retries": 1,
94   "custom_preset_models": [
95     "string"
96   ],
97   "image_assets": [
98     "string"
99   ],
100   "logs_retention_period_in_days": 1,
101   "is_extended_retention_enabled": true,
102   "is_custom_retention_enabled": true,
103   "starred": true,
104   "is_span_behaviors_enabled": true,
105   "curr_owner": 1
106 }

PATCH handler with superadmin lock and field protection.

Checks:

Object lock (is_managed=True -> non-superadmins can’t modify)
Field protection (non-superadmins can’t modify specific fields)

Authentication

AuthorizationBearer

JWT access token or Respan API key

Path parameters

unique_organization_idstringRequired

Request

This endpoint expects an object.

disabled_span_behaviorslist of stringsOptional

Behavior slugs excluded from span-behavior evaluation.

warnings_settingsobject or anyOptional

custom_property_index_mappingmap from strings to strings or nullOptional

Custom property key -> indexed ClickHouse column name (e.g. custom_string_1).

statusenumOptional

Staff-only ban/unban switch. Read-only (ignored) for non-staff callers.

active - active
inactive - inactive

logostring or nullOptional>=1 character

Send null to clear the organization logo. Uploading a new logo is a separate multipart operation: PATCH /user/organization/{unique_organization_id}/logo/.

created_atdatetime or nullOptional

first_api_call_atdatetime or nullOptional

last_api_call_atdatetime or nullOptional

notesstringOptional

namestringOptional1-254 characters

digest_email_inboxeslist of stringsOptional

organization_sizeintegerOptional-2147483648-2147483647

product_use_caseslist of stringsOptional

prioritize_objectiveslist of stringsOptional

unique_organization_idstringOptional>=1 character

budget_goalstringOptional

monthly_spendingdoubleOptional

preset_modelslist of stringsOptional

preset_optionstringOptional<=70 characters

dynamic_routing_enabledbooleanOptional

fallback_model_enabledbooleanOptional

fallback_modelslist of stringsOptional

alert_settingsanyOptional

system_fallback_enabledbooleanOptional

alerts_enabledbooleanOptional

disable_logbooleanOptional

has_api_callbooleanOptional

onboardedbooleanOptional

has_api_call_with_non_default_keybooleanOptional

onboarding_integration_optionsanyOptional

onboarding_keystringOptional<=50 characters

curr_onboarding_stepintegerOptional-2147483648-2147483647

onboarding_startdatetimeOptional

onboarding_enddatetime or nullOptional

enable_cachebooleanOptional

archive_durationintegerOptional-2147483648-2147483647

cache_saved_costdoubleOptional

cache_hit_countlongOptional-9223372036854776000-9223372036854776000

cache_hit_tokenslongOptional-9223372036854776000-9223372036854776000

omit_log_when_cache_hitbooleanOptional

cache_saved_timedoubleOptional

last_cache_aggregations_updatedatetimeOptional

classification_percentagedouble or nullOptional

use_custom_credentialsbooleanOptional

default_customer_user_budgetdouble or nullOptional

credit_low_balance_thresholddouble or nullOptional

Credit balance threshold (in USD) to trigger low balance warning webhook. When credit balance drops below this value, a credit_low_balance_threshold_reached webhook event is dispatched once until balance goes above threshold again.

credit_auto_top_off_thresholddouble or nullOptional

Credit balance threshold (in USD) to trigger auto top-off. When credit balance drops below this value, automatically charge credit_auto_top_off_amount via Stripe.

credit_auto_top_off_amountdouble or nullOptional

Amount (in USD) to automatically charge when credit balance drops below credit_auto_top_off_threshold. Requires stripe_customer_id with valid payment method.

is_auto_top_off_enabledbooleanOptional

Enable automatic credit top-off. When enabled and balance drops below credit_auto_top_off_threshold, automatically charges credit_auto_top_off_amount via Stripe. Requires stripe_customer_id with valid payment method.

metadata_keyslist of strings or nullOptional

custom_modelslist of strings or nullOptional

spend_capdouble or nullOptional

Spend cap amount in USD. Enforced in real-time via atomic Redis limiter.

spend_cap_warning_thresholddouble or nullOptional

Spend threshold in USD to trigger warning alert.

budget_durationenumOptional

Duration for spend_cap enforcement: daily, weekly, or monthly.

daily - daily
weekly - weekly
monthly - monthly

use_keywordsai_credentialsbooleanOptional

rate_limitdouble or nullOptional

customer_user_rate_limitdouble or nullOptional

retry_enabledbooleanOptional

retry_afterdoubleOptional

num_retriesintegerOptional-2147483648-2147483647

custom_preset_modelslist of stringsOptional

image_assetslist of stringsOptional

logs_retention_period_in_daysinteger or nullOptional-2147483648-2147483647

is_extended_retention_enabledbooleanOptional

is_custom_retention_enabledbooleanOptional

starredbooleanOptional

is_span_behaviors_enabledbooleanOptional

curr_ownerinteger or nullOptional

Response

idintegerRead-only

is_blockedbooleanRead-only

onboarding_methodenum or anyRead-only

namestring<=254 characters

statusenum

active - Active
deleting - Deleting
inactive - Inactive

stripe_customer_idstringRead-only

gateway_onboarding_completed_atdatetime or nullRead-only

tracing_onboarding_completed_atdatetime or nullRead-only

llm_gateway_markup_ratedoubleRead-only

LLM gateway markup rate (default 0% markup). Applied when Keywords AI provides LLM credentials. Formula: credit_charge = cost * (1 + llm_gateway_markup_rate)

company_organizationinteger or nullRead-only

userslist of integersRead-only

disabled_span_behaviorslist of strings

Behavior slugs excluded from span-behavior evaluation.

warnings_settingsobject or any

custom_property_index_mappingmap from strings to strings or null

Custom property key -> indexed ClickHouse column name (e.g. custom_string_1).

created_atdatetime or null

first_api_call_atdatetime or null

last_api_call_atdatetime or null

logostring or nullformat: "uri"

notesstring

digest_email_inboxeslist of strings

organization_sizeinteger-2147483648-2147483647

product_use_caseslist of strings

prioritize_objectiveslist of strings

unique_organization_idstring

budget_goalstring

monthly_spendingdouble

preset_modelslist of strings

preset_optionstring<=70 characters

dynamic_routing_enabledboolean

fallback_model_enabledboolean

fallback_modelslist of strings

alert_settingsany

system_fallback_enabledboolean

alerts_enabledboolean

disable_logboolean

has_api_callboolean

onboardedboolean

has_api_call_with_non_default_keyboolean

onboarding_integration_optionsany

onboarding_keystring<=50 characters

curr_onboarding_stepinteger-2147483648-2147483647

onboarding_startdatetime

onboarding_enddatetime or null

enable_cacheboolean

archive_durationinteger-2147483648-2147483647

cache_saved_costdouble

cache_hit_countlong-9223372036854776000-9223372036854776000

cache_hit_tokenslong-9223372036854776000-9223372036854776000

omit_log_when_cache_hitboolean

cache_saved_timedouble

last_cache_aggregations_updatedatetime

classification_percentagedouble or null

use_custom_credentialsboolean

default_customer_user_budgetdouble or null

credit_low_balance_thresholddouble or null

credit_auto_top_off_thresholddouble or null

Credit balance threshold (in USD) to trigger auto top-off. When credit balance drops below this value, automatically charge credit_auto_top_off_amount via Stripe.

credit_auto_top_off_amountdouble or null

Amount (in USD) to automatically charge when credit balance drops below credit_auto_top_off_threshold. Requires stripe_customer_id with valid payment method.

is_auto_top_off_enabledboolean

metadata_keyslist of strings or null

custom_modelslist of strings or null

spend_capdouble or null

Spend cap amount in USD. Enforced in real-time via atomic Redis limiter.

spend_cap_warning_thresholddouble or null

Spend threshold in USD to trigger warning alert.

budget_durationenum

Duration for spend_cap enforcement: daily, weekly, or monthly.

daily - daily
weekly - weekly
monthly - monthly

use_keywordsai_credentialsboolean

rate_limitdouble or null

customer_user_rate_limitdouble or null

retry_enabledboolean

retry_afterdouble

num_retriesinteger-2147483648-2147483647

custom_preset_modelslist of strings

image_assetslist of strings

logs_retention_period_in_daysinteger or null-2147483648-2147483647

is_extended_retention_enabledboolean

is_custom_retention_enabledboolean

starredboolean

is_span_behaviors_enabledboolean

curr_ownerinteger or null