> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/api-reference/organization-budgets.md).

# Organization budgets

## List Organization Budgets

> List the budgets this organization has defined. Owners and admins only.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationBudgetsPublic":{"properties":{"count":{"title":"Count","type":"integer"},"data":{"items":{"$ref":"#/components/schemas/OrganizationBudgetPublic"},"title":"Data","type":"array"}},"required":["data","count"],"title":"OrganizationBudgetsPublic","type":"object"},"OrganizationBudgetPublic":{"description":"One of the organization's budgets, and how much of its own config names it.\n\nCarries no spend rollup. ``BudgetResponse`` on the deployment surface sums\n``users.spend`` over the gateway's ``users`` table, which is deployment-wide\nand has no tenancy column, so the same figure here would be a cross-tenant\nread. What an organization's own spend is, is a question for Usage.\n\n``ceiling_count`` is the organization-relevant fact instead: how many of its\nceilings this budget currently holds, which is what makes a delete refuse.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"ceiling_count":{"title":"Ceiling Count","type":"integer"},"created_at":{"title":"Created At","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"organization_id":{"format":"uuid","title":"Organization Id","type":"string"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["budget_id","organization_id","name","max_budget","token_limit","request_limit","budget_duration_sec","reset_alignment","ceiling_count","created_at","updated_at"],"title":"OrganizationBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/budgets":{"get":{"description":"List the budgets this organization has defined. Owners and admins only.","operationId":"organization-budgets-list_organization_budgets","parameters":[{"description":"Number of records to skip","in":"query","name":"skip","required":false,"schema":{"default":0,"description":"Number of records to skip","minimum":0,"title":"Skip","type":"integer"}},{"description":"Maximum number of records to return","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Maximum number of records to return","maximum":1000,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationBudgetsPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Organization Budgets","tags":["organization-budgets"]}}}}
```

## Create Organization Budget

> Define a budget owned by this organization. Owners and admins only.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationBudgetCreate":{"description":"Create one budget owned by the caller's organization.","properties":{"budget_duration_sec":{"anyOf":[{"exclusiveMinimum":0,"type":"integer"},{"type":"null"}],"description":"Seconds between resets, counted from the last one. Mutually exclusive with reset_alignment","title":"Budget Duration Sec"},"max_budget":{"anyOf":[{"maximum":999999999999,"minimum":0,"type":"number"},{"type":"null"}],"description":"Maximum spend in USD over one period; null caps nothing","title":"Max Budget"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"description":"Admin-facing label for the budget","title":"Name"},"request_limit":{"anyOf":[{"maximum":1000000000000000,"minimum":0,"type":"integer"},{"type":"null"}],"description":"Maximum requests over one period; null caps nothing. Independent of max_budget","title":"Request Limit"},"reset_alignment":{"anyOf":[{"enum":["calendar_day","calendar_week","calendar_month"],"type":"string"},{"type":"null"}],"description":"Reset on a UTC calendar boundary instead of a fixed number of seconds, which is the only way to express a calendar month. Mutually exclusive with budget_duration_sec","title":"Reset Alignment"},"token_limit":{"anyOf":[{"maximum":1000000000000000,"minimum":0,"type":"integer"},{"type":"null"}],"description":"Maximum tokens over one period; null caps nothing. Independent of max_budget","title":"Token Limit"}},"title":"OrganizationBudgetCreate","type":"object"},"OrganizationBudgetPublic":{"description":"One of the organization's budgets, and how much of its own config names it.\n\nCarries no spend rollup. ``BudgetResponse`` on the deployment surface sums\n``users.spend`` over the gateway's ``users`` table, which is deployment-wide\nand has no tenancy column, so the same figure here would be a cross-tenant\nread. What an organization's own spend is, is a question for Usage.\n\n``ceiling_count`` is the organization-relevant fact instead: how many of its\nceilings this budget currently holds, which is what makes a delete refuse.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"ceiling_count":{"title":"Ceiling Count","type":"integer"},"created_at":{"title":"Created At","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"organization_id":{"format":"uuid","title":"Organization Id","type":"string"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["budget_id","organization_id","name","max_budget","token_limit","request_limit","budget_duration_sec","reset_alignment","ceiling_count","created_at","updated_at"],"title":"OrganizationBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/budgets":{"post":{"description":"Define a budget owned by this organization. Owners and admins only.","operationId":"organization-budgets-create_organization_budget","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationBudgetCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationBudgetPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Organization Budget","tags":["organization-budgets"]}}}}
```

## Update Organization Budget

> Change a budget's label, figure or period.\
> \
> Every ceiling naming it is held to the new figure from here on, which is the\
> point of naming a budget rather than typing an amount per place it applies.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationBudgetUpdate":{"description":"Replace a budget's label, figure and period.\n\nEvery field is optional and keyed on ``model_fields_set``, matching\nthe deployment-wide budget update's own: an *omitted* field is left alone, and an\nexplicit null clears it, so sending ``max_budget: null`` takes a budget back\nto uncapped, which is what the dashboard's dialog does. The period pair is\nstill mutually exclusive, and setting one does not clear the other, which is\nwhy :func:`_require_single_period_source` re-checks the *resulting* pair\nrather than the submitted one.","properties":{"budget_duration_sec":{"anyOf":[{"exclusiveMinimum":0,"type":"integer"},{"type":"null"}],"description":"Seconds between resets, counted from the last one. Mutually exclusive with reset_alignment","title":"Budget Duration Sec"},"max_budget":{"anyOf":[{"maximum":999999999999,"minimum":0,"type":"number"},{"type":"null"}],"description":"Maximum spend in USD over one period; null caps nothing","title":"Max Budget"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"description":"Admin-facing label for the budget","title":"Name"},"request_limit":{"anyOf":[{"maximum":1000000000000000,"minimum":0,"type":"integer"},{"type":"null"}],"description":"Maximum requests over one period; null caps nothing. Independent of max_budget","title":"Request Limit"},"reset_alignment":{"anyOf":[{"enum":["calendar_day","calendar_week","calendar_month"],"type":"string"},{"type":"null"}],"description":"Reset on a UTC calendar boundary instead of a fixed number of seconds, which is the only way to express a calendar month. Mutually exclusive with budget_duration_sec","title":"Reset Alignment"},"token_limit":{"anyOf":[{"maximum":1000000000000000,"minimum":0,"type":"integer"},{"type":"null"}],"description":"Maximum tokens over one period; null caps nothing. Independent of max_budget","title":"Token Limit"}},"title":"OrganizationBudgetUpdate","type":"object"},"OrganizationBudgetPublic":{"description":"One of the organization's budgets, and how much of its own config names it.\n\nCarries no spend rollup. ``BudgetResponse`` on the deployment surface sums\n``users.spend`` over the gateway's ``users`` table, which is deployment-wide\nand has no tenancy column, so the same figure here would be a cross-tenant\nread. What an organization's own spend is, is a question for Usage.\n\n``ceiling_count`` is the organization-relevant fact instead: how many of its\nceilings this budget currently holds, which is what makes a delete refuse.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"ceiling_count":{"title":"Ceiling Count","type":"integer"},"created_at":{"title":"Created At","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"organization_id":{"format":"uuid","title":"Organization Id","type":"string"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["budget_id","organization_id","name","max_budget","token_limit","request_limit","budget_duration_sec","reset_alignment","ceiling_count","created_at","updated_at"],"title":"OrganizationBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/budgets/{budget_id}":{"patch":{"description":"Change a budget's label, figure or period.\n\nEvery ceiling naming it is held to the new figure from here on, which is the\npoint of naming a budget rather than typing an amount per place it applies.","operationId":"organization-budgets-update_organization_budget","parameters":[{"in":"path","name":"budget_id","required":true,"schema":{"title":"Budget Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationBudgetUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationBudgetPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Update Organization Budget","tags":["organization-budgets"]}}}}
```

## Delete Organization Budget

> Delete a budget, refused with 409 while a ceiling or workspace default names it.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"Message":{"description":"A human-readable acknowledgment for an operation with nothing to return.","properties":{"message":{"description":"What happened.","title":"Message","type":"string"}},"required":["message"],"title":"Message","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/budgets/{budget_id}":{"delete":{"description":"Delete a budget, refused with 409 while a ceiling or workspace default names it.","operationId":"organization-budgets-delete_organization_budget","parameters":[{"in":"path","name":"budget_id","required":true,"schema":{"title":"Budget Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Organization Budget","tags":["organization-budgets"]}}}}
```

## List Organization Spend Ceilings

> List the ceilings capping identities inside this organization. Owners and admins only.\
> \
> A ceiling whose budget this organization does not own is listed with\
> \`\`manageable\`\` false rather than omitted: it is enforcing against this\
> organization's spend, so leaving it out would let the page read as uncapped.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationScopedBudgetsPublic":{"properties":{"count":{"title":"Count","type":"integer"},"data":{"items":{"$ref":"#/components/schemas/OrganizationScopedBudgetPublic"},"title":"Data","type":"array"}},"required":["data","count"],"title":"OrganizationScopedBudgetsPublic","type":"object"},"OrganizationScopedBudgetPublic":{"description":"One ceiling inside the organization, and the figures it enforces.\n\nThe limit and the period are read through the budget rather than stored here,\nand carried on the wire so a page can render a ceiling without fetching every\nbudget to resolve one id. Same reasoning as ``ScopedBudgetResponse``, whose\nshape this deliberately mirrors.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"manageable":{"title":"Manageable","type":"boolean"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at","manageable"],"title":"OrganizationScopedBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/spend-ceilings":{"get":{"description":"List the ceilings capping identities inside this organization. Owners and admins only.\n\nA ceiling whose budget this organization does not own is listed with\n``manageable`` false rather than omitted: it is enforcing against this\norganization's spend, so leaving it out would let the page read as uncapped.","operationId":"organization-budgets-list_organization_spend_ceilings","parameters":[{"description":"Number of records to skip","in":"query","name":"skip","required":false,"schema":{"default":0,"description":"Number of records to skip","minimum":0,"title":"Skip","type":"integer"}},{"description":"Maximum number of records to return","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Maximum number of records to return","maximum":1000,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationScopedBudgetsPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Organization Spend Ceilings","tags":["organization-budgets"]}}}}
```

## Create Organization Spend Ceiling

> Cap one identity in this organization at one of its budgets.\
> \
> Answers 404 when the scope names nothing in this organization, rather than\
> creating a ceiling that can never bind, and 404 when the budget is not this\
> organization's.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationScopedBudgetCreate":{"description":"Attach one of the organization's budgets to a scope inside it.","properties":{"budget_id":{"description":"The budget this ceiling enforces, which must be one this organization owns","maxLength":255,"minLength":1,"title":"Budget Id","type":"string"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"description":"Admin-facing label for this ceiling","title":"Name"},"provider_key_id":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\S+$","type":"string"},{"type":"null"}],"description":"Narrow the cap to one provider instance; omit or null to cap spend across every provider. A blank value would store a ceiling that never binds, so it is refused; this does not check that the value names a configured provider instance","title":"Provider Key Id"},"scope_id":{"description":"Id of the capped identity: this organization, one of its workspaces, a membership in either, or an API key in one","maxLength":255,"minLength":1,"title":"Scope Id","type":"string"},"scope_type":{"description":"Which kind of identity this ceiling caps","enum":["organization","workspace","workspace_member","org_member","api_token"],"title":"Scope Type","type":"string"}},"required":["scope_type","scope_id","budget_id"],"title":"OrganizationScopedBudgetCreate","type":"object"},"OrganizationScopedBudgetPublic":{"description":"One ceiling inside the organization, and the figures it enforces.\n\nThe limit and the period are read through the budget rather than stored here,\nand carried on the wire so a page can render a ceiling without fetching every\nbudget to resolve one id. Same reasoning as ``ScopedBudgetResponse``, whose\nshape this deliberately mirrors.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"manageable":{"title":"Manageable","type":"boolean"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at","manageable"],"title":"OrganizationScopedBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/spend-ceilings":{"post":{"description":"Cap one identity in this organization at one of its budgets.\n\nAnswers 404 when the scope names nothing in this organization, rather than\ncreating a ceiling that can never bind, and 404 when the budget is not this\norganization's.","operationId":"organization-budgets-create_organization_spend_ceiling","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationScopedBudgetCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationScopedBudgetPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Organization Spend Ceiling","tags":["organization-budgets"]}}}}
```

## Update Organization Spend Ceiling

> Relabel a ceiling, or point it at a different budget of this organization's.\
> \
> The scope and the provider narrowing are not editable: changing either would\
> move the ceiling to a different identity while carrying its spend, which is a\
> delete and a create.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrganizationScopedBudgetUpdate":{"description":"Relabel a ceiling, or point it at a different budget of this organization's.\n\nThe scope and the provider narrowing are not editable, for the reason\nthe deployment-wide ceiling update gives: changing either moves the ceiling to\na different identity while carrying its spend, which is a delete and a\ncreate, not an update.","properties":{"budget_id":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"title":"Budget Id"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"title":"Name"}},"title":"OrganizationScopedBudgetUpdate","type":"object"},"OrganizationScopedBudgetPublic":{"description":"One ceiling inside the organization, and the figures it enforces.\n\nThe limit and the period are read through the budget rather than stored here,\nand carried on the wire so a page can render a ceiling without fetching every\nbudget to resolve one id. Same reasoning as ``ScopedBudgetResponse``, whose\nshape this deliberately mirrors.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"manageable":{"title":"Manageable","type":"boolean"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at","manageable"],"title":"OrganizationScopedBudgetPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/spend-ceilings/{ceiling_id}":{"patch":{"description":"Relabel a ceiling, or point it at a different budget of this organization's.\n\nThe scope and the provider narrowing are not editable: changing either would\nmove the ceiling to a different identity while carrying its spend, which is a\ndelete and a create.","operationId":"organization-budgets-update_organization_spend_ceiling","parameters":[{"in":"path","name":"ceiling_id","required":true,"schema":{"title":"Ceiling Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationScopedBudgetUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationScopedBudgetPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Update Organization Spend Ceiling","tags":["organization-budgets"]}}}}
```

## Delete Organization Spend Ceiling

> Remove a ceiling inside this organization.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"Message":{"description":"A human-readable acknowledgment for an operation with nothing to return.","properties":{"message":{"description":"What happened.","title":"Message","type":"string"}},"required":["message"],"title":"Message","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/spend-ceilings/{ceiling_id}":{"delete":{"description":"Remove a ceiling inside this organization.","operationId":"organization-budgets-delete_organization_spend_ceiling","parameters":[{"in":"path","name":"ceiling_id","required":true,"schema":{"title":"Ceiling Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Organization Spend Ceiling","tags":["organization-budgets"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.otari.ai/api-reference/organization-budgets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.