> 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)\
> \
> \| Value | GROUP BY columns |\
> \|--------------|------------------------------------------------|\
> \| \`none\` | bucket only (default) |\
> \| \`user\` | bucket + \`user\_id\` |\
> \| \`user\_key\` | bucket + \`user\_id\` + \`key\_name\` |\
> \| \`model\` | bucket + \`model\` |\
> \| \`provider\` | bucket + \`provider\` |
```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","enum":["none","user","user_key","model","provider"],"description":"The grouping strategy that was applied."},"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` is `user` or `user_key`.\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` is\n`user` or `user_key` 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` is\n`user` or `user_key` 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` is `user_key`.\n`null` for requests with no named API key.\n"},"model":{"type":["string","null"],"description":"Present when `group_by` is `model`.\n`null` for requests where the model was not recorded.\n"},"provider":{"type":["string","null"],"description":"Present when `group_by` is `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\n| Value | GROUP BY columns |\n|--------------|------------------------------------------------|\n| `none` | bucket only (default) |\n| `user` | bucket + `user_id` |\n| `user_key` | bucket + `user_id` + `key_name` |\n| `model` | bucket + `model` |\n| `provider` | bucket + `provider` |\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":"Additional grouping dimension on top of the time bucket.","schema":{"type":"string","enum":["user","user_key","model","provider"]}},{"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` is `user_key` 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."}}}}}}
```
## Retrieve User Balance
> Retrieves the current balance information of 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":{"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/users/balance":{"get":{"summary":"Retrieve User Balance","tags":["User"],"description":"Retrieves the current balance information of the authenticated user. Requires a management API key for authentication.\n","responses":{"200":{"description":"Successfully retrieved user 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 – The provided API key is not a management key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error."}}}}}}
```
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.cortecs.ai/api-overview/management-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.