> For the complete documentation index, see [llms.txt](https://docs.cortecs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortecs.ai/api-overview/management-api.md).
# Management API
## Usage / Accounting
> Returns aggregated token and cost metrics bucketed by time and optionally by\
> user, API key, model, or provider.\
> \
> \*\*Time range\*\*\
> \- \`from\` defaults to the start of the current calendar day (UTC).\
> \- \`until\` defaults to the current moment (UTC).\
> \
> \*\*Bucket sizes\*\* (\`bucket\` parameter)\
> \
> \| Value | Meaning |\
> \|--------|------------------|\
> \| \`1h\` | 1 hour |\
> \| \`6h\` | 6 hours |\
> \| \`1d\` | 1 day (default) |\
> \| \`1w\` | 1 week |\
> \| \`1M\` | 1 month |\
> \| \`1Y\` | 1 year |\
> \
> \*\*Grouping\*\* (\`group\_by\` parameter)\
> \
> Comma-separated list of fields to group by (in addition to the time bucket).\
> Valid fields: \`user\_id\`, \`key\_name\`, \`model\`, \`provider\`.\
> \
> \| Example value | GROUP BY columns |\
> \|--------------------------|---------------------------------------------|\
> \| \*(omitted)\* | bucket only (default) |\
> \| \`user\_id\` | bucket + \`user\_id\` |\
> \| \`user\_id,key\_name\` | bucket + \`user\_id\` + \`key\_name\` |\
> \| \`user\_id,model\` | bucket + \`user\_id\` + \`model\` |\
> \| \`model\` | bucket + \`model\` |\
> \| \`provider\` | bucket + \`provider\` |\
> \| \`user\_id,key\_name,model\` | bucket + \`user\_id\` + \`key\_name\` + \`model\` |
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"UsageResponse":{"type":"object","required":["from","until","bucket","group_by","rows"],"properties":{"from":{"type":"string","format":"date-time","description":"Resolved inclusive start of the queried range (UTC)."},"until":{"type":"string","format":"date-time","description":"Resolved exclusive end of the queried range (UTC)."},"bucket":{"type":"string","enum":["1h","6h","1d","1w","1M","1Y"],"description":"The bucket interval used for aggregation."},"group_by":{"type":["string","null"],"description":"The comma-separated group_by fields that were applied.\n`null` when no grouping was requested.\n"},"user_id":{"type":["string","null"],"description":"The `user_id` filter that was applied, if any."},"key_name":{"type":["string","null"],"description":"The `key_name` filter that was applied, if any."},"model":{"type":["string","null"],"description":"The `model` filter that was applied, if any."},"provider":{"type":["string","null"],"description":"The `provider` filter that was applied, if any."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/UsageRow"},"description":"Aggregated rows ordered by `bucket_start ASC`, then `user_id ASC`,\nthen `key_name ASC`, then `model ASC`, then `provider ASC` (where applicable).\n"}}},"UsageRow":{"type":"object","required":["bucket_start","bucket_end","request_count","input_tokens","output_tokens","total_tokens","audio_duration","input_price","output_price","audio_price","cache_read_price","cache_write_price","speech_price","total_price","cache_read_tokens","cache_write_tokens","character_count"],"properties":{"bucket_start":{"type":"string","format":"date-time","description":"Inclusive start of the aggregation bucket (UTC)."},"bucket_end":{"type":"string","format":"date-time","description":"Exclusive end of the aggregation bucket (UTC).\nEqual to `bucket_start + bucket_interval`.\n"},"user_id":{"type":["string","null"],"description":"Present when `group_by` includes `user_id`.\n`null` for requests that had no user context.\n"},"user_email":{"type":["string","null"],"description":"Resolved email address of the user. Present when `group_by` includes\n`user_id` and the user could be found in the team.\n`null` if the user is not a current team member.\n"},"user_name":{"type":["string","null"],"description":"Resolved display name of the user. Present when `group_by` includes\n`user_id` and the user could be found in the team.\n`null` if the user has no name set or is not a current team member.\n"},"key_name":{"type":["string","null"],"description":"Present when `group_by` includes `key_name`.\n`null` for requests with no named API key.\n"},"model":{"type":["string","null"],"description":"Present when `group_by` includes `model`.\n`null` for requests where the model was not recorded.\n"},"provider":{"type":["string","null"],"description":"Present when `group_by` includes `provider`.\n`null` for requests where the provider was not recorded.\n"},"request_count":{"type":"integer","format":"int64","description":"Number of individual inference requests in this bucket."},"input_tokens":{"type":"integer","format":"int64","description":"Total prompt / input tokens consumed, including cache-read and cache-write tokens.\n"},"output_tokens":{"type":"integer","format":"int64","description":"Total completion / output tokens generated."},"total_tokens":{"type":"integer","format":"int64","description":"`input_tokens + output_tokens`"},"audio_duration":{"type":"number","format":"double","description":"Total audio duration in seconds (STT/TTS workloads)."},"input_price":{"type":"number","format":"double","description":"Aggregated cost for input tokens in USD."},"output_price":{"type":"number","format":"double","description":"Aggregated cost for output tokens in USD."},"audio_price":{"type":"number","format":"double","description":"Aggregated cost for audio processing in USD."},"cache_read_price":{"type":"number","format":"double","description":"Aggregated cost for cache-read tokens in USD."},"cache_write_price":{"type":"number","format":"double","description":"Aggregated cost for cache-write tokens in USD."},"total_price":{"type":"number","format":"double","description":"`input_price + output_price + audio_price + cache_read_price + cache_write_price + speech_price`\n"},"cache_read_tokens":{"type":"integer","format":"int64","description":"Tokens served from prompt cache (subset of `input_tokens`)."},"cache_write_tokens":{"type":"integer","format":"int64","description":"Tokens written to prompt cache (subset of `input_tokens`)."},"character_count":{"type":"integer","format":"int64","description":"Total character count across all requests in this bucket."},"speech_price":{"type":"number","format":"double","description":"Aggregated cost for speech synthesis (TTS) in USD."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}},"ValidationErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","required":["loc","msg","type"],"properties":{"loc":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"description":"Location of the offending field."},"msg":{"type":"string","description":"Validation error message."},"type":{"type":"string","description":"Pydantic error type code."}}}}}}}},"paths":{"/manage/usage":{"get":{"operationId":"getUsage","summary":"Usage / Accounting","tags":["Usage"],"description":"Returns aggregated token and cost metrics bucketed by time and optionally by\nuser, API key, model, or provider.\n\n**Time range**\n- `from` defaults to the start of the current calendar day (UTC).\n- `until` defaults to the current moment (UTC).\n\n**Bucket sizes** (`bucket` parameter)\n\n| Value | Meaning |\n|--------|------------------|\n| `1h` | 1 hour |\n| `6h` | 6 hours |\n| `1d` | 1 day (default) |\n| `1w` | 1 week |\n| `1M` | 1 month |\n| `1Y` | 1 year |\n\n**Grouping** (`group_by` parameter)\n\nComma-separated list of fields to group by (in addition to the time bucket).\nValid fields: `user_id`, `key_name`, `model`, `provider`.\n\n| Example value | GROUP BY columns |\n|--------------------------|---------------------------------------------|\n| *(omitted)* | bucket only (default) |\n| `user_id` | bucket + `user_id` |\n| `user_id,key_name` | bucket + `user_id` + `key_name` |\n| `user_id,model` | bucket + `user_id` + `model` |\n| `model` | bucket + `model` |\n| `provider` | bucket + `provider` |\n| `user_id,key_name,model` | bucket + `user_id` + `key_name` + `model` |\n","parameters":[{"name":"from","in":"query","required":false,"description":"Inclusive start of the time range (ISO 8601 / RFC 3339).\nDefaults to the start of the current UTC day.\n","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Exclusive end of the time range (ISO 8601 / RFC 3339).\nDefaults to the current UTC moment.\n","schema":{"type":"string","format":"date-time"}},{"name":"bucket","in":"query","required":false,"description":"TimescaleDB `time_bucket` interval for aggregation.","schema":{"type":"string","enum":["1h","1d","1w","1M","1Y"]}},{"name":"group_by","in":"query","required":false,"description":"Comma-separated list of fields to group by, in addition to the time bucket.\nValid fields: `user_id`, `key_name`, `model`, `provider`.\nExamples: `user_id`, `user_id,model`, `user_id,key_name,provider`.\n","schema":{"type":"string"}},{"name":"user_id","in":"query","required":false,"description":"Filter results to a single user.","schema":{"type":"string"}},{"name":"key_name","in":"query","required":false,"description":"Filter results to a specific API key name.\nOnly effective when `group_by` includes `key_name` or used as a standalone filter.\n","schema":{"type":"string"}},{"name":"model","in":"query","required":false,"description":"Filter results to a single model name.","schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"description":"Filter results to a single provider.","schema":{"type":"string"}}],"responses":{"200":{"description":"Usage rows matching the requested filters and grouping.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token does not have permission to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error (missing required parameters or wrong type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"500":{"description":"Internal server error (DB unreachable, query timeout, etc.).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## List API Keys
> Returns all API keys belonging to the authenticated user. Requires a management API key for authentication.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ApiKey":{"type":"object","properties":{"name":{"type":"string","description":"The unique name of the API key."},"created_at":{"type":"integer","description":"Unix timestamp (seconds) of when the key was created."},"is_management_key":{"type":"boolean","description":"Whether this key has management permissions."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/api-keys":{"get":{"summary":"List API Keys","tags":["API Keys"],"description":"Returns all API keys belonging to the authenticated user. Requires a management API key for authentication.\n","responses":{"200":{"description":"Successfully returned the list of API keys.","content":{"application/json":{"schema":{"type":"object","properties":{"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create API Key
> Creates a new API key for the authenticated user. Requires a management API key for authentication.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/api-keys":{"post":{"summary":"Create API Key","tags":["API Keys"],"description":"Creates a new API key for the authenticated user. Requires a management API key for authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A unique name for the new API key."},"is_management_key":{"type":"boolean","description":"Whether the new key should have management permissions.","default":false}}}}}},"responses":{"201":{"description":"API key created successfully. The `api_key` value is only shown once.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the created key."},"is_management_key":{"type":"boolean","description":"Whether the key has management permissions."},"api_key":{"type":"string","description":"The API key token. Store it securely — it cannot be retrieved again."}}}}}},"400":{"description":"Bad request – Invalid input, duplicate name, or key limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Delete API Key
> Deletes an API key by name. Also removes any associated budget configurations. You cannot delete the management key currently being used to authenticate. Requires a management API key for authentication.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/api-keys":{"delete":{"summary":"Delete API Key","tags":["API Keys"],"description":"Deletes an API key by name. Also removes any associated budget configurations. You cannot delete the management key currently being used to authenticate. Requires a management API key for authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the API key to delete."}}}}}},"responses":{"200":{"description":"API key deleted successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted":{"type":"string","description":"The name of the deleted key."}}}}}},"400":{"description":"Bad request – Invalid input or attempting to delete the key in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – The specified API key does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Retrieve Current Project Settings
> Retrieves the current project settings and configuration details. Requires a management API key for authentication.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ProjectConfig":{"type":"object","required":["_id","project_id","inference_config","allow_overwrite","created_at","updated_at"],"properties":{"_id":{"type":"string","description":"Unique identifier of the project configuration."},"project_id":{"type":"string","description":"Identifier of the project this configuration belongs to."},"inference_config":{"type":"object","description":"The inference configuration for the project.","properties":{"allowed_providers":{"type":"array","description":"List of allowed providers.","items":{"type":"string"}},"eu_native":{"type":"boolean","description":"Whether to use only EU-based and regulated providers. Even when false, all endpoints are GDPR compliant."},"allow_quantization":{"type":"boolean","description":"Whether to allow quantization of the model. Quantization is only supported for some providers."},"allow_zero_data_retention":{"type":"boolean","description":"Whether to use only ZDR providers."},"enable_model_fallback":{"type":"boolean","description":"Whether to allow model fallback when a model is currently unavailable."},"preference":{"type":"string","description":"Preference for handling the request.","enum":["speed","cost","balanced"],"nullable":true},"max_tokens":{"type":"integer","description":"Maximum tokens allowed in output.","nullable":true}}},"allow_overwrite":{"type":"boolean","description":"Allow individual API calls to define their own inference configurations. If disabled, the global settings below will be enforced for all requests."},"created_at":{"type":"string","format":"date-time","description":"Date and time when this configuration was created."},"updated_at":{"type":"string","format":"date-time","description":"Date and time when this configuration was last updated."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/project-configs":{"get":{"summary":"Retrieve Current Project Settings","tags":["Project Config"],"description":"Retrieves the current project settings and configuration details. Requires a management API key for authentication.\n","responses":{"200":{"description":"Successfully returned the current project settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfig"}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
## Update Current Project Settings
> Updates the current project settings and configuration details. Restricted to project admins. Requires a management API key for authentication.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ProjectConfigUpdateRequest":{"type":"object","description":"A request object for updating the project configuration. Required fields must be included, while other fields are optional. This endpoint is restricted to admins unless allow_overwrite is set to true.\n","required":["inference_config","created_at","updated_at"],"properties":{"inference_config":{"type":"object","description":"The inference configuration for the project.","properties":{"allowed_providers":{"type":"array","description":"List of allowed providers.","items":{"type":"string"}},"eu_native":{"type":"boolean","description":"Whether to consider only providers based and regulated within the EU. Even when false, all our endpoints are GDPR compliant."},"allow_quantization":{"type":"boolean","description":"Whether to allow quantized endpoints."},"max_tokens":{"type":"integer","description":"Maximum tokens allowed in output.","nullable":true},"preference":{"type":"string","description":"Preference for handling the request.","enum":["speed","cost","balanced"],"nullable":true},"allow_zero_data_retention":{"type":"boolean","description":"Whether to use only ZDR providers."},"enable_model_fallback":{"type":"boolean","description":"Whether to allow model fallback when a model is currently unavailable."}}},"allow_overwrite":{"type":"boolean","description":"Allow individual API calls to define their own inference configurations. If disabled, the global settings below will be enforced for all requests.\n","nullable":true},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the configuration was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the configuration was last updated."}}},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"description":"Indicates whether the operation was successful."},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/project-configs":{"put":{"summary":"Update Current Project Settings","tags":["Project Config"],"description":"Updates the current project settings and configuration details. Restricted to project admins. Requires a management API key for authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfigUpdateRequest"}}}},"responses":{"200":{"description":"Project configuration updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad Request – Invalid configuration or registry validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – Not a management key or user is not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
## List Budgets
> Lists budget rules for the authenticated project. Non-admin management key holders can see budgets that apply to them. Project admins can see all project budgets and can filter by scope, period, user\_id, and key\_name.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"BudgetsResponse":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","items":{"$ref":"#/components/schemas/Budget"}}}},"Budget":{"type":"object","required":["scope","period","amount","user_id","key_name"],"properties":{"scope":{"type":"string","enum":["project","user","api-key"],"description":"Budget scope."},"period":{"type":"string","enum":["daily","weekly","monthly"],"description":"Budget period."},"amount":{"type":"integer","minimum":0,"description":"Budget amount."},"user_id":{"type":["string","null"],"description":"User identifier for user and api-key scoped budgets."},"key_name":{"type":["string","null"],"description":"API key name for api-key scoped budgets."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/budgets":{"get":{"summary":"List Budgets","tags":["Budgets"],"description":"Lists budget rules for the authenticated project. Non-admin management key holders can see budgets that apply to them. Project admins can see all project budgets and can filter by scope, period, user_id, and key_name.\n","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["project","user","api-key"]}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["daily","weekly","monthly"]}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"key_name","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully returned budgets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetsResponse"}}}},"400":{"description":"Invalid filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
## Upsert Budget
> Creates or updates a budget period for the authenticated project. Restricted to project admins using a management API key. PUT is also supported with the same body.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"BudgetUpsertRequest":{"type":"object","required":["scope","period","amount"],"properties":{"scope":{"type":"string","enum":["project","user","api-key"]},"period":{"type":"string","enum":["daily","weekly","monthly"]},"user_id":{"type":["string","null"],"description":"Required for user scope and concrete api-key budgets. Must be null or omitted when key_name is '*' for api-key scope.","default":null},"key_name":{"type":["string","null"],"description":"Required for api-key scope. Use '*' with user_id null for the default per-api-key budget; otherwise user_id is required and the key must belong to that user.","default":null},"amount":{"type":"integer","minimum":0}}},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"description":"Indicates whether the operation was successful."},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/budgets":{"post":{"summary":"Upsert Budget","tags":["Budgets"],"description":"Creates or updates a budget period for the authenticated project. Restricted to project admins using a management API key. PUT is also supported with the same body.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetUpsertRequest"}}}},"responses":{"200":{"description":"Budget saved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid budget request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Not a management key or user is not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
## Delete Budget
> Deletes a single budget period for the provided scope. Restricted to project admins using a management API key. The request body may be JSON, or the same fields may be provided as query parameters.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"BudgetDeleteRequest":{"type":"object","required":["scope","period"],"properties":{"scope":{"type":"string","enum":["project","user","api-key"]},"period":{"type":"string","enum":["daily","weekly","monthly"]},"user_id":{"type":["string","null"],"description":"Required for user scope and concrete api-key budgets. Must be null or omitted when key_name is '*' for api-key scope.","default":null},"key_name":{"type":["string","null"],"description":"Required for api-key scope. Use '*' with user_id null for the default per-api-key budget; otherwise user_id is required and the key must belong to that user.","default":null}}},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"description":"Indicates whether the operation was successful."}}},"paths":{"/manage/budgets":{"delete":{"summary":"Delete Budget","tags":["Budgets"],"description":"Deletes a single budget period for the provided scope. Restricted to project admins using a management API key. The request body may be JSON, or the same fields may be provided as query parameters.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetDeleteRequest"}}}},"responses":{"200":{"description":"Budget deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid budget delete request."},"401":{"description":"Unauthorized - Missing or invalid token."},"403":{"description":"Forbidden - Not a management key or user is not an admin."},"404":{"description":"Not Found - Project configuration not found."},"500":{"description":"Internal server error."}}}}}}
```
## Retrieve Project Balance
> Retrieves the current balance information of the authenticated project. Requires a management API key belonging to a project admin.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"UserBalance":{"type":"object","properties":{"current_balance":{"type":"number","format":"float","description":"The current balance of the user."},"currency":{"type":"string","description":"The currency in which the balance is expressed."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/balance":{"get":{"summary":"Retrieve Project Balance","tags":["Balance"],"description":"Retrieves the current balance information of the authenticated project. Requires a management API key belonging to a project admin.\n","responses":{"200":{"description":"Successfully retrieved project balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserBalance"}}}},"401":{"description":"Unauthorized – Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – Not a management key or user is not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
## List Project Members
> Returns all members of the authenticated project. Requires a management API key belonging to a project admin.
```json
{"openapi":"3.1.0","info":{"title":"Cortecs Management API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A management API key must be used as the Bearer token."}},"schemas":{"ProjectMembersResponse":{"type":"object","required":["members"],"properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/ProjectMember"}}}},"ProjectMember":{"type":"object","required":["id","name","email","role"],"properties":{"id":{"type":"string","description":"The Auth0 user identifier of the project member."},"name":{"type":"string","description":"The display name of the project member."},"email":{"type":"string","format":"email","description":"The email address of the project member."},"role":{"type":["string","null"],"description":"The project role of the member."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A human-readable error message."},"detail":{"type":"string","description":"A human-readable error detail message."}}}}},"paths":{"/manage/project-members":{"get":{"summary":"List Project Members","tags":["Project"],"description":"Returns all members of the authenticated project. Requires a management API key belonging to a project admin.\n","responses":{"200":{"description":"Successfully returned the project members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMembersResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Not a management key or user is not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Project configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```