> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a new budget > Creates a new budget in the workspace. Exactly one scope variant must be set (workspace / project / identity / api_key / provider / model). At least one of `limits.amount`, `limits.token_limit`, or `rate_limit.requests_per_minute` MUST be provided. Uniqueness is enforced across (workspace_id, scope_kind, scope_target_id). ## OpenAPI ````yaml post /v2/budgets openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/budgets: post: tags: - Budgets summary: Create a new budget description: >- Creates a new budget in the workspace. Exactly one scope variant must be set (workspace / project / identity / api_key / provider / model). At least one of `limits.amount`, `limits.token_limit`, or `rate_limit.requests_per_minute` MUST be provided. Uniqueness is enforced across (workspace_id, scope_kind, scope_target_id). operationId: BudgetCreate requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBudgetRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateBudgetResponse' x-code-samples: - lang: typescript label: Node.js source: > await orq.budgets.create({ scope: { kind: "workspace" }, limits: { period: "MONTHLY", amount: 1000 } }); components: schemas: CreateBudgetRequest: type: object properties: scope: allOf: - $ref: '#/components/schemas/BudgetScope' description: Exactly one variant must be set. limits: allOf: - $ref: '#/components/schemas/BudgetLimits' description: >- At least one of amount / token_limit / rate_limit.requests_per_minute must be provided on the budget; the handler enforces that invariant. rate_limit: allOf: - $ref: '#/components/schemas/RateLimit' description: Optional rate limit. is_active: type: boolean description: |- Whether the budget should be active immediately. Defaults to true when omitted (handler enforces). expires_at: type: string description: |- Optional expiration. When set in combination with is_active=true, the value MUST be in the future; the handler rejects past values. format: date-time CreateBudgetResponse: type: object properties: budget: allOf: - $ref: '#/components/schemas/Budget' description: Newly created budget. BudgetScope: type: object properties: workspace: $ref: '#/components/schemas/WorkspaceBudgetScope' project: $ref: '#/components/schemas/ProjectBudgetScope' identity: $ref: '#/components/schemas/IdentityBudgetScope' api_key: $ref: '#/components/schemas/ApiKeyBudgetScope' provider: $ref: '#/components/schemas/ProviderBudgetScope' model: $ref: '#/components/schemas/ModelBudgetScope' description: |- BudgetScope is a closed oneof. Exactly one variant must be set. The six variants are ordered by enforcement precedence (most specific to most general) and mirror the BudgetScopeKind filter enum. BudgetLimits: type: object properties: period: $ref: '#/components/schemas/BudgetPeriod' amount: type: number format: double token_limit: type: string description: |- BudgetLimits is the per-period spend and token ceiling. At least one of `amount`, `token_limit`, or RateLimit.requests_per_minute MUST be set on a Budget; that invariant is enforced by the handler. RateLimit: type: object properties: requests_per_minute: type: integer format: int32 description: |- RateLimit is the per-minute request ceiling. Enforced via atomic increment-first semantics in the enforcement middleware. Budget: type: object properties: budget_id: type: string workspace_id: type: string scope: $ref: '#/components/schemas/BudgetScope' limits: $ref: '#/components/schemas/BudgetLimits' rate_limit: $ref: '#/components/schemas/RateLimit' is_active: type: boolean expires_at: format: date-time type: string created_at: format: date-time type: string updated_at: format: date-time type: string description: |- Budget is the canonical record stored in MongoDB `budgets.entities`. It replaces the embedded `constraints.budget` on api-keys and the legacy CONTACT-only `budgets.configs` collection (see ADR 0007). WorkspaceBudgetScope: type: object properties: {} description: Workspace-wide ceiling. The implicit target is the caller's workspace. ProjectBudgetScope: type: object properties: project_id: type: string description: Per-project cap. IdentityBudgetScope: type: object properties: identity_external_id: type: string description: |- Per-identity cap. Keyed by the contact's external_id (not the internal Mongo `_id`) so the scope is stable across imports. ApiKeyBudgetScope: type: object properties: api_key_id: type: string description: |- Per-api-key cap. Replaces the legacy embedded `constraints.budget` on auth.apiKeys. ProviderBudgetScope: type: object properties: provider: type: string description: |- Per-provider cap. The value is the provider enum string (e.g. "openai", "anthropic") drawn from ModelIntegrationIdentifier. ModelBudgetScope: type: object properties: model_id: type: string description: |- Per-model cap. The value is the provider-issued literal model_id (e.g. "gpt-4o") — NOT the Mongo `_id` of the model master-data document — so the scope is stable across workspaces. BudgetPeriod: type: string enum: - BUDGET_PERIOD_UNSPECIFIED - BUDGET_PERIOD_DAILY - BUDGET_PERIOD_WEEKLY - BUDGET_PERIOD_MONTHLY - BUDGET_PERIOD_YEARLY - BUDGET_PERIOD_ONE_TIME securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````