Ctrlk
cortecs.aiModelsLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Management API

List API Keys

get

Returns all API keys belonging to the authenticated user. Requires a management API key for authentication.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Responses
200

Successfully returned the list of API keys.

application/json
get/manage/api-keys
GET /v1/manage/api-keys HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "api_keys": [
    {
      "name": "my-production-key",
      "team_id": "Default",
      "created_at": 1715100000,
      "is_management_key": false
    },
    {
      "name": "admin-key",
      "team_id": "Operations",
      "created_at": 1715100500,
      "is_management_key": true
    }
  ]
}

Create API Key

post

Creates a new API key for the authenticated user. Requires a management API key for authentication.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
namestring · max: 50Required

A unique name for the new API key. Only letters, numbers, hyphens, underscores, and whitespace are allowed.

Example: my-new-keyPattern: ^[A-Za-z0-9_\s-]+$
team_idstringOptional

A team currently assigned to the authenticated user. Defaults to the team assigned to the management API key used for this request when omitted or blank. Legacy management keys without a team resolve to the system-managed Default team.

Example: Default
is_management_keybooleanOptional

Whether the new key should have management permissions.

Default: false
Responses
201

API key created successfully. The api_key value is only shown once.

application/json
namestringOptional

The name of the created key.

team_idstringOptional

The team assigned to the created key.

is_management_keybooleanOptional

Whether the key has management permissions.

api_keystringOptional

The API key token. Store it securely — it cannot be retrieved again.

post/manage/api-keys
POST /v1/manage/api-keys HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "name": "my-new-key",
  "team_id": "Default",
  "is_management_key": false
}
{
  "name": "my-new-key",
  "team_id": "Default",
  "is_management_key": false,
  "api_key": "[API-KEY]"
}

Delete API Key

delete

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.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
namestringRequired

The name of the API key to delete.

Example: my-old-key
Responses
200

API key deleted successfully.

application/json
successbooleanOptionalExample: true
deletedstringOptional

The name of the deleted key.

delete/manage/api-keys
DELETE /v1/manage/api-keys HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "name": "my-old-key"
}
{
  "success": true,
  "deleted": "my-old-key"
}

Retrieve Current Project Settings

get

Retrieves effective settings for one team. Admins may retrieve any team in the project. Members may retrieve only teams they are assigned to. Any user may provide team_id; when omitted, it defaults to the team assigned to the management API key. Legacy keys without a team use Default. Default always resolves to the global project configuration. Other teams without an explicit override use the global project configuration.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
team_idstringOptional

Team to retrieve. Default selects the global project configuration. Members must be assigned to the requested team. Omit to use the team assigned to the authenticated management API key, or Default for a legacy key without a team.

Responses
200

Successfully returned the current project settings.

application/json

Settings for one team. The optional team_id query parameter selects the team; when omitted, the team is derived from the authenticated API key, or Default for a legacy key without a team.

allow_overwritebooleanOptional

Allow individual API calls to define their own inference configurations. If disabled, the selected team's settings will be enforced for all requests.

Example: false
team_idstringRequired

Selected team. Legacy API keys without a team use Default.

get/manage/project-configs
GET /v1/manage/project-configs HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "team_id": "Research",
  "inference_config": {
    "allowed_providers": [
      "scaleway"
    ],
    "eu_native": false,
    "allow_quantization": true,
    "allow_zero_data_retention": false,
    "enable_model_fallback": true
  },
  "allow_overwrite": false
}

Update Current Project Settings

put

Updates one team's project configuration. Pass team_id to select a team, or omit it to use the team assigned to the management API key. Default updates the global project configuration. Legacy keys without a team use Default. Restricted to project admins. Requires a management API key for authentication.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
team_idstringOptional

Team override to update. Default updates the global project configuration. Omit to use the team assigned to the authenticated management API key, or Default for a legacy key without a team.

Body

Settings for one team. The optional team_id query parameter selects the team; when omitted, the team is derived from the authenticated API key, or Default for a legacy key without a team.

allow_overwritebooleanOptional

Allow individual API calls to define their own inference configurations. If disabled, the selected team's settings will be enforced for all requests.

Example: false
Responses
200

Project configuration updated successfully.

application/json

Indicates whether the operation was successful.

successbooleanOptionalExample: true
put/manage/project-configs
PUT /v1/manage/project-configs HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "inference_config": {
    "allowed_providers": [
      "mistral",
      "scaleway"
    ],
    "preference": "speed",
    "eu_native": false,
    "allow_quantization": true,
    "allow_zero_data_retention": false,
    "enable_model_fallback": true
  },
  "allow_overwrite": false
}
{
  "success": true
}

Remove Team Project Settings Override

delete

Removes a team's explicit settings so it uses the Default team configuration. The Default team configuration cannot be removed. Restricted to project admins. Requires a management API key for authentication.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
team_idstringOptional

Team override to remove. Default is the global project configuration and cannot be removed. Omit to use the team assigned to the authenticated management API key, or Default for a legacy key without a team.

Responses
200

Team override removed successfully.

application/json

Indicates whether the operation was successful.

successbooleanOptionalExample: true
delete/manage/project-configs
DELETE /v1/manage/project-configs HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true
}

List Budgets

get

Lists budget rules for the authenticated project. Non-admin management key holders receive only their effective rules; a generic * period is omitted when a specific rule overrides that period. Project admins receive all stored rules, including overridden generic rules. Results can be filtered by scope, period, team_id, user_id, and key_name.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
scopestring · enumOptionalPossible values:
periodstring · enumOptionalPossible values:
user_idstringOptional
team_idstringOptional
key_namestringOptional
Responses
200

Successfully returned budgets.

application/json
get/manage/budgets
GET /v1/manage/budgets HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "budgets": [
    {
      "scope": "api-key",
      "period": "monthly",
      "amount": 1000,
      "team_id": "Research",
      "user_id": "auth0|1234567890",
      "key_name": "prod-key"
    }
  ]
}

Upsert Budget

post

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.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
scopestring · enumRequiredPossible values:
periodstring · enumRequiredPossible values:
team_idstring · nullableOptional

Required for team scope. Use * for the default per-team budget or a project team name for a specific team.

Default: null
user_idstring · nullableOptional

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_namestring · nullableOptional

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
amountintegerRequired
Responses
200

Budget saved successfully.

application/json

Indicates whether the operation was successful.

successbooleanOptionalExample: true
post/manage/budgets
POST /v1/manage/budgets HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "scope": "api-key",
  "period": "monthly",
  "user_id": "auth0|1234567890",
  "key_name": "prod-key",
  "amount": 1000
}
{
  "success": true
}

Upsert Budget

put

Same behavior as POST /manage/budgets.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
scopestring · enumRequiredPossible values:
periodstring · enumRequiredPossible values:
team_idstring · nullableOptional

Required for team scope. Use * for the default per-team budget or a project team name for a specific team.

Default: null
user_idstring · nullableOptional

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_namestring · nullableOptional

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
amountintegerRequired
Responses
200

Budget saved successfully.

application/json

Indicates whether the operation was successful.

successbooleanOptionalExample: true
put/manage/budgets
PUT /v1/manage/budgets HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "scope": "project",
  "period": "daily",
  "team_id": null,
  "user_id": null,
  "key_name": null,
  "amount": 1
}
{
  "success": true
}

Delete Budget

delete

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.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
scopestring · enumRequiredPossible values:
periodstring · enumRequiredPossible values:
team_idstring · nullableOptional

Required for team scope. Use * for the default per-team budget or a project team name for a specific team.

Default: null
user_idstring · nullableOptional

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_namestring · nullableOptional

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
Responses
200

Budget deleted successfully.

application/json

Indicates whether the operation was successful.

successbooleanOptionalExample: true
delete/manage/budgets
DELETE /v1/manage/budgets HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "scope": "api-key",
  "period": "monthly",
  "user_id": "auth0|1234567890",
  "key_name": "prod-key"
}
{
  "success": true
}

Retrieve Project Balance

get

Retrieves the current balance information of the authenticated project. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Responses
200

Successfully retrieved project balance.

application/json
current_balancenumber · floatOptional

The current balance of the user.

Example: 1234.56
currencystringOptional

The currency in which the balance is expressed.

Example: EUR
get/manage/balance
GET /v1/manage/balance HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "current_balance": 1234.56,
  "currency": "EUR"
}

List Project Members

get

Returns all members of the authenticated project. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Responses
200

Successfully returned the project members.

application/json
get/manage/project-members
GET /v1/manage/project-members HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "members": [
    {
      "id": "auth0|1234567890",
      "name": "Alice Smith",
      "email": "alice@example.com",
      "role": "admin"
    },
    {
      "id": "auth0|9876543210",
      "name": "Bob Lee",
      "email": "bob@example.com",
      "role": "member"
    }
  ]
}

Invite Project Members

post

Invites one or more email addresses to the authenticated project with either the member or admin role. Up to 50 unique addresses can be supplied in one request. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
emailsstring · email[] · min: 1 · max: 50Required

Email addresses to invite. Duplicate addresses are ignored case-insensitively. Addresses that already belong to project members or have an existing invitation are reported as failures and are not invited.

rolestring · enumOptional

Organization role granted to every invitee when the invitation is accepted.

Default: memberPossible values:
Responses
201

All invitations were created successfully.

application/json
post/manage/project-members
POST /v1/manage/project-members HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "emails": [
    "alice@example.com"
  ],
  "role": "member"
}
{
  "invitations": [
    {
      "id": "invitation_123",
      "email": "alice@example.com"
    }
  ],
  "failures": []
}

List Teams

get

Returns the named teams for the authenticated project, including the system-managed Default team. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Responses
200

Successfully returned the project teams.

application/json
teamsstring[]RequiredExample: ["Default","Platform","Customer Success"]
get/manage/teams
GET /v1/manage/teams HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "teams": [
    "Default",
    "Platform",
    "Customer Success"
  ]
}

Create Team

post

Adds a unique custom team name to the authenticated project. Default is reserved. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
team_idstring · min: 1 · max: 50Required

The team name. Only letters, numbers, hyphens, underscores, and whitespace are allowed. Leading and trailing whitespace is removed. Default is reserved for the system-managed fallback team.

Example: PlatformPattern: ^[A-Za-z0-9_\s-]+$
Responses
201

Team created successfully.

application/json
team_idstringRequiredExample: Platform
post/manage/teams
POST /v1/manage/teams HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "team_id": "Platform"
}
{
  "team_id": "Platform"
}

Delete Team

delete

Removes a custom team from the authenticated project. The system-managed Default team cannot be deleted. Members left without a team are assigned to Default. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
team_idstring · min: 1 · max: 50Required

The team name. Only letters, numbers, hyphens, underscores, and whitespace are allowed. Leading and trailing whitespace is removed. Default is reserved for the system-managed fallback team.

Example: PlatformPattern: ^[A-Za-z0-9_\s-]+$
Responses
200

Team deleted successfully.

application/json
successconst: Required
deletedstringRequiredExample: Platform
delete/manage/teams
DELETE /v1/manage/teams HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "team_id": "Platform"
}
{
  "success": true,
  "deleted": "Platform"
}

List Team Members

get

Returns the project members assigned to a team. Requires a management API key belonging to a project admin.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
team_idstring · min: 1 · max: 50Required
Responses
200

Team membership returned successfully.

application/json
team_idstringRequiredExample: Platform
user_idsstring[]RequiredExample: ["auth0|1234567890","auth0|9876543210"]
get/manage/teams/members
GET /v1/manage/teams/members?team_id=text HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "team_id": "Platform",
  "user_ids": [
    "auth0|1234567890",
    "auth0|9876543210"
  ]
}

Assign Team Members

post

Assigns any number of project members to a team in one request. Existing assignments, including Default, are unchanged.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
team_idstring · min: 1 · max: 50RequiredExample: Platform
user_idsstring[] · min: 1RequiredExample: ["auth0|1234567890","auth0|9876543210"]
Responses
200

Project members assigned successfully.

application/json
team_idstringRequired
assignedstring[]Required
post/manage/teams/members
POST /v1/manage/teams/members HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "team_id": "Platform",
  "user_ids": [
    "auth0|1234567890",
    "auth0|9876543210"
  ]
}
{
  "team_id": "text",
  "assigned": [
    "text"
  ]
}

Unassign Team Members

delete

Unassigns any number of project members from a team in one request. Removing Default requires every affected member to belong to another team. Removing a custom team restores Default for members who would otherwise have no team.

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Body
team_idstring · min: 1 · max: 50RequiredExample: Platform
user_idsstring[] · min: 1RequiredExample: ["auth0|1234567890","auth0|9876543210"]
Responses
200

Project members unassigned successfully.

application/json
team_idstringRequired
unassignedstring[]Required
delete/manage/teams/members
DELETE /v1/manage/teams/members HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "team_id": "Platform",
  "user_ids": [
    "auth0|1234567890",
    "auth0|9876543210"
  ]
}
{
  "team_id": "text",
  "unassigned": [
    "text"
  ]
}

Usage / Accounting

get

Returns aggregated token and cost metrics bucketed by time and optionally by team, 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

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: team_id, user_id, key_name, model, provider.

Example value
GROUP BY columns

(omitted)

bucket only (default)

team_id

bucket + team_id

team_id,model

bucket + team_id + model

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

Authorizations
AuthorizationstringRequired

A management API key must be used as the Bearer token.

Query parameters
fromstring · date-timeOptional

Inclusive start of the time range (ISO 8601 / RFC 3339). Defaults to the start of the current UTC day.

Example: 2025-05-01T00:00:00Z
untilstring · date-timeOptional

Exclusive end of the time range (ISO 8601 / RFC 3339). Defaults to the current UTC moment.

Example: 2025-05-31T23:59:59Z
bucketstring · enumOptional

TimescaleDB time_bucket interval for aggregation.

Example: 1dPossible values:
group_bystringOptional

Comma-separated list of fields to group by, in addition to the time bucket. Valid fields: team_id, user_id, key_name, model, provider. Examples: team_id, team_id,model, user_id,key_name,provider.

Example: user_id
team_idstringOptional

Filter results to a single team.

Example: Research
user_idstringOptional

Filter results to a single user.

Example: user_42
key_namestringOptional

Filter results to a specific API key name. Only effective when group_by includes key_name or used as a standalone filter.

Example: prod-key
modelstringOptional

Filter results to a single model name.

Example: gpt-4o
providerstringOptional

Filter results to a single provider.

Example: openai
byokboolean · nullableOptional

Filter by whether the request used the project's own provider key. true returns only BYOK usage, false excludes BYOK usage, and null or omission returns all usage.

Example: false
Responses
200

Usage rows matching the requested filters and grouping.

application/json
fromstring · date-timeRequired

Resolved inclusive start of the queried range (UTC).

Example: 2025-05-01T00:00:00Z
untilstring · date-timeRequired

Resolved exclusive end of the queried range (UTC).

Example: 2025-05-31T23:59:59Z
bucketstring · enumRequired

The bucket interval used for aggregation.

Example: 1dPossible values:
group_bystring · nullableRequired

The comma-separated group_by fields that were applied. null when no grouping was requested.

Example: user_id
team_idstring · nullableOptional

The team_id filter that was applied, if any.

Example: Research
user_idstring · nullableOptional

The user_id filter that was applied, if any.

Example: user_42
key_namestring · nullableOptional

The key_name filter that was applied, if any.

Example: prod-key
modelstring · nullableOptional

The model filter that was applied, if any.

Example: gpt-4o
providerstring · nullableOptional

The provider filter that was applied, if any.

Example: openai
byokboolean · nullableRequired

The BYOK filter that was applied. null means all usage.

Example: false
get/manage/usage
GET /v1/manage/usage HTTP/1.1
Host: api.cortecs.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "from": "2025-05-01T00:00:00Z",
  "until": "2025-05-31T23:59:59Z",
  "bucket": "1d",
  "group_by": null,
  "byok": null,
  "rows": [
    {
      "bucket_start": "2025-05-01T00:00:00Z",
      "bucket_end": "2025-05-02T00:00:00Z",
      "request_count": 1240,
      "input_tokens": 520000,
      "output_tokens": 180000,
      "total_tokens": 700000,
      "audio_duration": 0,
      "input_price": 1.56,
      "output_price": 3.6,
      "audio_price": 0,
      "cache_read_price": 0.08,
      "cache_write_price": 0.02,
      "total_price": 5.26,
      "cache_read_tokens": 40000,
      "cache_write_tokens": 8000,
      "character_count": 250000,
      "speech_price": 0
    }
  ]
}
PreviousOCR [BETA]
NextSecurity & Compliance

Last updated