--- updatedAt: 2026-07-22T12:59:17.000Z agentTools: projectIndex: https://developer.doit.com/llms.txt --- # Create an allocation Creates a new allocation. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "DoiT Cloud Intelligence", "description": "Programmatic access to DoiT Platform", "version": "v1" }, "servers": [ { "url": "https://api.doit.com" } ], "security": [ { "api_key": [] }, { "tenantId": [], "api_key": [] } ], "tags": [ { "name": "Allocations", "description": "Define how costs are distributed across your organization." } ], "paths": { "/analytics/v1/allocations": { "post": { "tags": [ "Allocations" ], "summary": "Create an allocation", "description": "Creates a new allocation.", "operationId": "createAllocation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAllocationRequest" } } } }, "responses": { "200": { "description": "OK - The request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Allocation" } } }, "links": { "getAllocation": { "operationId": "getAllocation", "parameters": { "id": "$response.body#/id" } }, "updateAllocation": { "operationId": "updateAllocation", "parameters": { "id": "$response.body#/id" } }, "deleteAllocation": { "operationId": "deleteAllocation", "parameters": { "id": "$response.body#/id" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "x-codegen-request-body-name": "Body" } } }, "components": { "schemas": { "AllocationComponent": { "required": [ "key", "type", "values", "mode" ], "type": "object", "description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.", "properties": { "key": { "type": "string", "description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions." }, "type": { "$ref": "#/components/schemas/AllocationDimensionsTypes" }, "values": { "type": "array", "description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.", "items": { "type": "string" } }, "inverse": { "type": "boolean", "description": "If true, all selected values will be excluded.", "default": false }, "includeNull": { "type": "boolean", "description": "Include null values.", "default": false }, "caseInsensitive": { "type": "boolean", "description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.", "default": false }, "mode": { "type": "string", "description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.", "enum": [ "is", "starts_with", "ends_with", "contains", "regexp" ] } } }, "CreateAllocationRequest": { "required": [ "name", "description" ], "type": "object", "description": "Request body for creating an allocation.", "properties": { "name": { "type": "string", "description": "Allocation name." }, "description": { "type": "string", "description": "Allocation description." }, "anomalyDetection": { "type": "boolean", "description": "Whether anomaly detection is enabled for this allocation. Only applicable to single allocations." }, "rule": { "$ref": "#/components/schemas/AllocationRule" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/GroupAllocationRule" } }, "unallocatedCosts": { "type": "string", "description": "Custom label for values that do not fit into allocation (required for group type allocation).", "nullable": true }, "folderId": { "type": "string", "description": "Identifier of the folder that contains the allocation. Set to \"root\" if the allocation is at the top level (not in a folder).", "default": "root", "example": "root" } } }, "AllocationRule": { "required": [ "components", "formula" ], "type": "object", "description": "Single allocation rule. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.", "nullable": true, "properties": { "components": { "type": "array", "description": "List of allocation filter components.", "items": { "$ref": "#/components/schemas/AllocationComponent" } }, "formula": { "type": "string", "description": "Formula for combining components (A is the first component, B is the second one, etc.).", "example": "A AND B" }, "validityPeriods": { "type": "array", "nullable": true, "description": "Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies.", "items": { "$ref": "#/components/schemas/AllocationRulePeriod" } } } }, "AllocationRulePeriod": { "type": "object", "description": "A date range when a rule applies. startDate and endDate are both inclusive, so a handover between two rules needs a one-day gap: the first rule's endDate the day before, the second rule's startDate the handover day. Only the first period in the list may omit startDate, and only the last may omit endDate.", "properties": { "startDate": { "type": "string", "nullable": true, "description": "Start date (YYYY-MM-DD, UTC), inclusive. Absent means no lower bound.", "example": "2026-03-15" }, "endDate": { "type": "string", "nullable": true, "description": "End date (YYYY-MM-DD, UTC), inclusive. Absent means no upper bound.", "example": "2026-06-15" } } }, "AllocationValueExtraction": { "type": "object", "nullable": true, "required": [ "sources" ], "description": "Makes the rule emit a value extracted from the first non-empty source instead of the rule name.", "properties": { "sources": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Ordered extraction sources; the first non-empty value wins.", "items": { "$ref": "#/components/schemas/AllocationValueExtractionSource" } }, "onMissing": { "type": "string", "description": "What happens when every source is missing or empty on a matching row. \"useFallback\" (default) emits the fallback value, which is required in that mode; \"nextRule\" lets the row fall through to the next rule in the group.", "enum": [ "useFallback", "nextRule" ], "default": "useFallback" }, "fallback": { "type": "string", "nullable": true, "description": "Literal emitted when every source is missing. Required with onMissing \"useFallback\" (the default); not allowed with onMissing \"nextRule\"." } } }, "AllocationValueExtractionSource": { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "description": "The dimension type to read the value from. Label-map types (label, tag, project_label, system_label, gke_label) extract the value of the given key; \"fixed\" extracts a raw table dimension (for example project_id, service_description, region). Derived dimensions such as credits are not extractable.", "enum": [ "label", "tag", "project_label", "system_label", "gke_label", "fixed" ] }, "key": { "type": "string", "description": "The label/tag key, or the fixed dimension ID, whose value is extracted." }, "providers": { "type": "array", "nullable": true, "description": "Optional cloud providers this source applies to.", "items": { "type": "string" } } } }, "AllocationDimensionsTypes": { "description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.", "type": "string", "enum": [ "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label" ], "x-enumDescriptions": { "fixed": "Standard built-in billing dimensions.", "label": "Customer-defined resource labels; key is the label key.", "tag": "AWS cost allocation tags; key is the tag key.", "project_label": "Google Cloud project-level labels.", "system_label": "DoiT- or provider-generated system labels.", "optional": "Console grouping for label/tag keys; use a concrete subtype in filters.", "datetime": "Time dimensions for date-based filtering.", "allocation_rule": "Reference another allocation rule by ID.", "gke": "Google Kubernetes Engine cost-allocation dimensions.", "gke_label": "GKE workload labels." } }, "Error": { "type": "object", "description": "Standard error response structure.", "properties": { "error": { "type": "string", "description": "Detailed error message." } } }, "Allocation": { "type": "object", "description": "Allocation object, including rules and metadata.", "properties": { "id": { "type": "string", "description": "Allocation ID." }, "name": { "type": "string", "description": "Allocation name." }, "description": { "type": "string", "description": "Allocation description." }, "type": { "type": "string", "description": "Type of allocation (preset or custom)." }, "allocationType": { "type": "string", "description": "Composition type of allocation.", "enum": [ "single", "group" ] }, "createTime": { "type": "integer", "description": "The time when the allocation was created (in UNIX timestamp).", "format": "int64" }, "updateTime": { "type": "integer", "description": "Last time the allocation was modified (in UNIX timestamp).", "format": "int64" }, "anomalyDetection": { "type": "boolean", "description": "Whether anomaly detection is enabled for this allocation. Only applicable to single allocations." }, "rule": { "$ref": "#/components/schemas/AllocationRule" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/GroupAllocationRule" } }, "unallocatedCosts": { "type": "string", "description": "Custom label for values that do not fit into allocation (required for group type allocation).", "nullable": true }, "folderId": { "type": "string", "description": "Identifier of the folder that contains the allocation. Set to \"root\" if the allocation is at the top level (not in a folder).", "default": "root", "example": "root" } } }, "GroupAllocationRule": { "required": [ "action" ], "type": "object", "nullable": true, "description": "Allocation rule for a group type allocation. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.", "properties": { "name": { "type": "string", "description": "Name of the allocation rule." }, "description": { "type": "string", "description": "Description of the allocation rule." }, "action": { "type": "string", "description": "Action to perform with this rule.", "enum": [ "create", "update", "select" ] }, "id": { "type": "string", "description": "ID of existing allocation (required for 'update' or 'select' action)." }, "components": { "type": "array", "description": "List of allocation filter components (required for 'create' or 'update' action). Can include components of type \"allocation_rule\" to reference existing allocation rules.", "items": { "$ref": "#/components/schemas/AllocationComponent" } }, "formula": { "type": "string", "description": "Formula for combining components (A is the first component, B is the second one, etc.)", "example": "A AND B" }, "valueExtraction": { "$ref": "#/components/schemas/AllocationValueExtraction" }, "validityPeriods": { "type": "array", "nullable": true, "description": "Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies.", "items": { "$ref": "#/components/schemas/AllocationRulePeriod" } } } } }, "responses": { "400": { "description": "Bad Request - The server cannot process the request, often due to a malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - The client is not authorized to perform the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found - The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "Authorization", "description": "Use the \"Bearer \" format or sign in for autofill", "in": "header" }, "tenantId": { "type": "apiKey", "name": "X-Tenant-Id", "description": "Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer ` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.", "in": "header" } } }, "x-samples-languages": [ "curl", "go", "node", "python" ], "x-cli-config": { "security": "oauth2", "params": { "client_id": "cli" } } } ```