API docs by Redocly

AI Platform API (2026-10)

Download OpenAPI specification:Download

Management API for the GreenNode AI Platform — manage API keys, enable models, track spend, and configure rate limits and guardrails.

This document covers the management API only. Calling a model is out of scope here.

Before you start

Authentication. All endpoints use the standard VNG Cloud OAuth2 flow. See the Authorization section on the API documentation home page: obtain a client ID and client secret from VNG Cloud IAM, exchange them at the authorization server for an access_token, then send Authorization: Bearer <access_token> with every request.

Versions in the path. Endpoints live under both /v1 and /v2. Use exactly the path shown in this document for each operation — it is the officially supported one. Some operations also exist on an older version and behave identically, but others exist on one version only, so swapping v1 for v2 (or the reverse) on the same path may return 404. When a version is superseded, this document is updated first.

Resource identifiers. Endpoints taking {apiKeyName} accept either the key id or the key name. Prefer the id (auth-<uuid>, from GET /v1/api-keys): it does not change when a key is renamed. {modelUuid}, {guardrailsId} and {rateLimitConfigId} accept ids only.

API key type. Every API key created through this document is of the same type and the type field always returns normal. If your account holds a key issued by a service plan, these endpoints return 403 for that key — contact support.

Token-credit. The AI Platform uses its own credit unit called a token-credit, at a rate of 1 token-credit = 1 credit (the GreenNode account credit). GET /v1/user-credit returns the granted and consumed amounts for your account.

Conventions. Timestamps sent in a request body are epoch milliseconds; timestamps returned are ISO-8601 with a +07:00 offset, for example 2026-10-01T10:12:44.000+07:00. In Cost & usage and Log, multi-value filters (modelUuids, apiKeyIds, providers) are comma-separated strings; everywhere else they are JSON arrays — check the schema of each endpoint. Creating or deleting an API key and enabling or disabling a model are asynchronous: the response returns before the work is finished, so read the resource back to confirm.

Errors. Every error response has the shape {"message": "..."}. For status 500 the message is always the literal Internal Server Error. One inconsistency to be aware of: the API Keys and Models groups return 400 when a resource is not found, while Rate limit and Guardrails return 404 — handle both.

API Keys

Create, list and delete API keys. A key is the credential used to call models.

Create an API key

Creates a new API key. The call is asynchronous — the response returns immediately with status CREATING.

A key takes tens of seconds to a few minutes to become usable (up to ~5 minutes under heavy load).

Only one key operation runs at a time: if another key is CREATING or DELETING, the request is rejected. Create keys one after another.

To know when the key is ready: poll GET /v1/api-keys/{apiKeyName} every 5-10 seconds (allow at least a 10-minute timeout) until status is ACTIVE (ready) or ERROR (failed — delete that key and create a new one; keys in ERROR do not count towards your quota).

Once the key is ACTIVE, enable models for your account with POST /v2/models/user-settings before calling any model.

Request Body schema: application/json
name
required
string [ 5 .. 35 ] characters ^[a-z0-9][a-z0-9\-]{3,33}[a-z0-9]$

5-35 characters: lowercase a-z, digits 0-9 and hyphens only. It must NOT start or end with a hyphen. Uppercase letters, spaces and accented characters are rejected

Responses

Request samples

Content type
application/json
{
  • "name": "my-service-key"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete multiple API keys

Each entry accepts a key id or a key name.

Request Body schema: application/json
apiKeyNames
required
Array of strings non-empty

Key ids (recommended) or key names. Obtain from GET /v1/api-keys.

Responses

Request samples

Content type
application/json
{
  • "apiKeyNames": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Delete an API key

Accepts either the key id (auth-<uuid>) or the display name. Deletion is asynchronous — the key moves to DELETING and then disappears from the list.

path Parameters
apiKeyName
required
string
Example: auth-5ba35dbd-b2b6-4ec4-94ab-e78bf9613af3

Key id (recommended) or key name. Get the id from GET /v1/api-keys (field id). Prefer the id — it does not change when the key is renamed

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v2/api-keys/%7BapiKeyName%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

List API keys

Returns the API keys of your account, with pagination and filtering.

query Parameters
page
integer
Example: page=1

Page number, starting at 1. Pagination only applies when BOTH page and size are sent — omit either one and the full list is returned

size
integer
Example: size=20

Items per page. Must be sent together with page

name
string
Example: name=my-

Filter by key name — SUBSTRING match anywhere in the name, case-insensitive

from
string <date-time>
Example: from=2026-10-01T00:00:00Z

Start of range, ISO-8601 in UTC ending with Z. When from/to are supplied the filter applies to the DELETION time and deleted keys are included. Omit both to return only live keys

to
string <date-time>
Example: to=2026-11-01T00:00:00Z

End of range, ISO-8601 in UTC ending with Z. Use together with from

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/api-keys',
  qs: {
    page: '1',
    size: '20',
    name: 'my-',
    from: '2026-10-01T00:00:00Z',
    to: '2026-11-01T00:00:00Z'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Get an API key

Status, creation time and the models the key may call.

path Parameters
apiKeyName
required
string
Example: auth-5ba35dbd-b2b6-4ec4-94ab-e78bf9613af3

Key id (recommended) or key name. Get the id from GET /v1/api-keys (field id). Prefer the id — it does not change when the key is renamed

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/api-keys/%7BapiKeyName%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the rate-limit of an API key

The rate-limit config currently applied to this key. If no rate-limit is attached, the response is {"data": null} with status 200.

path Parameters
apiKeyName
required
string
Example: auth-5ba35dbd-b2b6-4ec4-94ab-e78bf9613af3

Key id (recommended) or key name. Get the id from GET /v1/api-keys (field id). Prefer the id — it does not change when the key is renamed

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/api-keys/%7BapiKeyName%7D/rate-limit-config'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Models

Browse models and enable or disable them for your account.

List models

Models available to your account, including whether each one is enabled.

query Parameters
page
integer
Example: page=1

Page number, starting at 1. Pagination only applies when BOTH page and size are sent — omit either one and the full list is returned

size
integer
Example: size=20

Items per page. Must be sent together with page

status
string
Enum: "enabled" "disabled"
Example: status=enabled

Filter by enabled state for your account

name
string
Example: name=gpt

Filter by model name — partial match

providers
Array of strings
Example: providers=openai&providers=google

Filter by provider — values come from GET /v1/models/metadata

modelTypes
Array of strings
Example: modelTypes=chat

Filter by model type — values come from GET /v1/models/metadata

useCases
Array of strings
Example: useCases=coding

Filter by use case — values come from GET /v1/models/metadata

backendTypes
Array of strings
Example: backendTypes=selfhost

Filter by where the model runs — values come from GET /v1/models/metadata

byGroup
boolean
Default: false
Example: byGroup=false

Group variants of the same model family together

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/models',
  qs: {
    page: '1',
    size: '20',
    status: 'enabled',
    name: 'gpt',
    providers: 'openai,google',
    modelTypes: 'chat',
    useCases: 'coding',
    backendTypes: 'selfhost',
    byGroup: 'false'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Get a model

Description, context length, pricing and use cases.

path Parameters
modelUuid
required
string
Example: 8f14e45f-ceea-467a-9c1f-4b1c3a6d2e90

Model UUID. Obtain from GET /v1/models (field uuid)

query Parameters
byGroup
boolean
Default: false
Example: byGroup=false

Return the model grouped with its family

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/models/detail/%7BmodelUuid%7D',
  qs: {byGroup: 'false'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get filter metadata

The allowed values for the filter query parameters of GET /v1/models.

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/models/metadata'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Enable or disable models

Turns models on or off for your account. The call is asynchronous.

Before calling: your account must be activated with available credit (GET /v1/user-credit returns status: ACTIVE) and must already have at least one ACTIVE API key.

Each model has a cooldown between state changes — see the 429 response.

Request Body schema: application/json
Array
modelUuid
required
string

Model UUID. Obtain from GET /v1/models.

enabled
required
boolean

true enables the model for your account

types
Array of strings

Task types to enable. Only values listed in the model's own types field are accepted (see GET /v1/models/detail/{modelUuid}). Omit to enable every type the model supports

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Get the platform rate-limit of a model

The platform default limits for this model, broken down by account tier.

path Parameters
modelUuid
required
string
Example: 8f14e45f-ceea-467a-9c1f-4b1c3a6d2e90

Model UUID. Obtain from GET /v1/models (field uuid)

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/models/rate-limit/%7BmodelUuid%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cost & usage

Token-credit balance and the cost you have incurred.

Get cost by provider and model

Cost over a time range, grouped by provider and by model. Billable usage only.

Request Body schema: application/json
from
integer <int64>

Start of range, epoch milliseconds

to
integer <int64>

End of range, epoch milliseconds

apiKeyIds
string

Key ids, comma-separated with no spaces. Obtain from GET /v1/api-keys.

providers
string

Provider codes, comma-separated. Obtain from GET /v1/models/metadata (field providers[].code).

modelUuids
string

Model UUIDs, comma-separated with no spaces. Obtain from GET /v1/models.

Responses

Request samples

Content type
application/json
{
  • "from": 1790787600000,
  • "to": 1793466000000,
  • "providers": "openai,google"
}

Response samples

Content type
application/json
{
  • "totalCost": 6438786,
  • "byProvider": [
    ],
  • "byModel": [
    ]
}

Get daily cost for a month

query Parameters
year
integer
Example: year=2026

Year. Omit for the current year

month
integer
Example: month=10

Month 1-12. Omit for the current month

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/cost/monthly-trend',
  qs: {year: '2026', month: '10'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "year": 2026,
  • "month": 10,
  • "days": [
    ]
}

Get token-credit balance

Available balance = (quota - used) + (freeQuota - freeUsed), counting only pools that have not expired. The free pool is consumed first, then quota.

Responses

Request samples 

const request = require('request');

const options = {method: 'GET', url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/user-credit'};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Rate limit

Define request and token limits, then attach them to models or API keys.

List rate-limit configs

query Parameters
page
integer
Example: page=1

Page number, starting at 1. Pagination only applies when BOTH page and size are sent — omit either one and the full list is returned

size
integer
Example: size=20

Items per page. Must be sent together with page

name
string
Example: name=team-

Filter by name — partial match, case-insensitive

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/rate-limit-config',
  qs: {page: '1', size: '20', name: 'team-'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Create a rate-limit config

Creates a rate-limit config and optionally attaches it to models or API keys right away.

Request Body schema: application/json
is_requests
boolean
Default: false

Enable the request-count limit. Note: this field is named is_requests in REQUESTS but comes back as requests in RESPONSES — do not copy a response body straight back into a request

requestsLimit
integer <int64> [ 1 .. 100000000 ]
Default: 100

Maximum number of requests per window

requestsTimeUnit
string
Default: "minute"
Enum: "minute" "hour" "day" "month"

Length of the request-counting window

requestsWindowType
string
Default: "fixed"
Value: "fixed"

Always send fixed — the counter resets at the start of each requestsTimeUnit, it is not a sliding window

is_tokens
boolean
Default: false

Enable the token-count limit. In responses this field is named tokens

tokensLimit
integer <int64> [ 100 .. 5000000000 ]
Default: 100000

Maximum number of tokens per window

tokensTimeUnit
string
Default: "minute"
Enum: "minute" "hour" "day" "month"

Length of the token-counting window

tokensWindowType
string
Default: "fixed"
Value: "fixed"

Always send fixed

name
required
string^[a-z0-9\-]{5,100}$

5-100 characters: lowercase a-z, digits 0-9 and hyphens only. Uppercase letters, spaces and accented characters are rejected

modelUuids
Array of strings

Model UUIDs. Obtain from GET /v1/models.

associatedApiKeys
Array of strings

Key ids. Obtain from GET /v1/api-keys.

Responses

Request samples

Content type
application/json
{
  • "name": "team-a-limit",
  • "is_requests": true,
  • "requestsLimit": 1000,
  • "requestsTimeUnit": "minute",
  • "requestsWindowType": "fixed",
  • "is_tokens": true,
  • "tokensLimit": 2000000,
  • "tokensTimeUnit": "minute",
  • "tokensWindowType": "fixed",
  • "modelUuids": [
    ],
  • "associatedApiKeys": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a rate-limit config

path Parameters
rateLimitConfigId
required
string
Example: a7d3e1b8-5c94-4f20-b6e1-93c7a0d4f512

Rate-limit config id. Obtain from GET /v1/rate-limit-config

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/rate-limit-config/%7BrateLimitConfigId%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update rate-limit thresholds

path Parameters
rateLimitConfigId
required
string
Example: a7d3e1b8-5c94-4f20-b6e1-93c7a0d4f512

Rate-limit config id. Obtain from GET /v1/rate-limit-config

Request Body schema: application/json
is_requests
boolean
Default: false

Enable the request-count limit. Note: this field is named is_requests in REQUESTS but comes back as requests in RESPONSES — do not copy a response body straight back into a request

requestsLimit
integer <int64> [ 1 .. 100000000 ]
Default: 100

Maximum number of requests per window

requestsTimeUnit
string
Default: "minute"
Enum: "minute" "hour" "day" "month"

Length of the request-counting window

requestsWindowType
string
Default: "fixed"
Value: "fixed"

Always send fixed — the counter resets at the start of each requestsTimeUnit, it is not a sliding window

is_tokens
boolean
Default: false

Enable the token-count limit. In responses this field is named tokens

tokensLimit
integer <int64> [ 100 .. 5000000000 ]
Default: 100000

Maximum number of tokens per window

tokensTimeUnit
string
Default: "minute"
Enum: "minute" "hour" "day" "month"

Length of the token-counting window

tokensWindowType
string
Default: "fixed"
Value: "fixed"

Always send fixed

modelUuids
Array of strings

Omit to keep the current models. Send a list to REPLACE the whole set — any model not in the list is detached. Send [] to detach all. Obtain from GET /v1/models.

Responses

Request samples

Content type
application/json
{
  • "is_requests": true,
  • "requestsLimit": 2000,
  • "requestsTimeUnit": "minute",
  • "requestsWindowType": "fixed",
  • "is_tokens": false,
  • "modelUuids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Delete a rate-limit config

path Parameters
rateLimitConfigId
required
string
Example: a7d3e1b8-5c94-4f20-b6e1-93c7a0d4f512

Rate-limit config id. Obtain from GET /v1/rate-limit-config

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/rate-limit-config/%7BrateLimitConfigId%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Rename a rate-limit config

This endpoint changes the name only. There is no description field.

path Parameters
rateLimitConfigId
required
string
Example: a7d3e1b8-5c94-4f20-b6e1-93c7a0d4f512

Rate-limit config id. Obtain from GET /v1/rate-limit-config

Request Body schema: application/json
name
required
string^[a-z0-9\-]{5,100}$

5-100 characters: lowercase a-z, digits 0-9 and hyphens only. Uppercase letters, spaces and accented characters are rejected

Responses

Request samples

Content type
application/json
{
  • "name": "team-a-limit"
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Attach a rate-limit config to models

A model or API key belongs to exactly one rate-limit config. To move one to a different config, detach it from the current config first.

path Parameters
rateLimitConfigId
required
string
Example: a7d3e1b8-5c94-4f20-b6e1-93c7a0d4f512

Rate-limit config id. Obtain from GET /v1/rate-limit-config

Request Body schema: application/json
modelUuids
required
Array of strings

REPLACES the whole set of models. Any model currently attached but missing from this list is DETACHED. Send [] to detach all. Obtain from GET /v1/models.

associatedApiKeys
Array of strings

Omit this field to keep the currently attached keys. Send [] to detach all. Send a list to replace the whole set. Obtain from GET /v1/api-keys.

Responses

Request samples

Content type
application/json
{
  • "modelUuids": [
    ],
  • "associatedApiKeys": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Guardrails

Content-control rules: PII filters, word filters and prompt-based rules.

List guardrails

query Parameters
page
integer
Example: page=1

Page number, starting at 1. Pagination only applies when BOTH page and size are sent — omit either one and the full list is returned

size
integer
Example: size=20

Items per page. Must be sent together with page

name
string
Example: name=pii-

Filter by name — partial match, case-insensitive

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/guardrails',
  qs: {page: '1', size: '20', name: 'pii-'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Create a guardrail

Creates a content-control rule set: PII filter, word filter and prompt-based rules.

Request Body schema: application/json
name
required
string^[a-z0-9\-]{5,100}$

5-100 characters: lowercase a-z, digits 0-9 and hyphens only. Uppercase letters, spaces and accented characters are rejected

description
string <= 255 characters

Free-text note so you can recognise this guardrail

object (PiiConfigCreate)

PII settings when CREATING a guardrail — regularExpression is nested here

object (WordFilterConfig)
Array of objects (PromptRule)

Responses

Request samples

Content type
application/json
{
  • "name": "pii-block",
  • "description": "Block e-mail addresses and national ID numbers",
  • "pii": {
    },
  • "wordFilter": {
    },
  • "promptBased": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete multiple guardrails

Request Body schema: application/json
guardrailsIds
required
Array of strings non-empty

Guardrail ids to delete. Obtain from GET /v1/guardrails.

Responses

Request samples

Content type
application/json
{
  • "guardrailsIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a guardrail

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/guardrails/%7BguardrailsId%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a guardrail

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/guardrails/%7BguardrailsId%7D'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

List PII types

The PII types you can select in a PII filter. Use the code value as piiTypeCode.

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://aiplatform-hcm.api.vngcloud.vn/v1/guardrails/pii/types'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "listData": [
    ]
}

Rename a guardrail

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Request Body schema: application/json
name
required
string^[a-z0-9\-]{5,100}$

5-100 characters: lowercase a-z, digits 0-9 and hyphens only. Uppercase letters, spaces and accented characters are rejected

description
string <= 255 characters

Free-text note so you can recognise this guardrail

Responses

Request samples

Content type
application/json
{
  • "name": "pii-block",
  • "description": "Block e-mail addresses and national ID numbers"
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Update the PII filter

Configures which PII types to detect and any custom regular expressions.

Note the placement of regularExpression: on POST /v1/guardrails it sits inside pii; here it sits alongside pii. Putting it in the wrong place silently drops it.

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Request Body schema: application/json
object (PiiConfig)

PII settings when UPDATING — regularExpression goes alongside this object, not inside it

Array of objects (RegexRule)

Responses

Request samples

Content type
application/json
{
  • "pii": {
    },
  • "regularExpression": [
    ]
}

Response samples

Content type
application/json
{
  • "data": "b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84"
}

Update prompt-based rules

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Request Body schema: application/json
Array of objects (PromptRule)

Responses

Request samples

Content type
application/json
{
  • "promptBased": [
    ]
}

Response samples

Content type
application/json
{
  • "data": "b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84"
}

Update the word filter

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Request Body schema: application/json
object (WordFilterConfig)

Responses

Request samples

Content type
application/json
{
  • "wordFilter": {
    }
}

Response samples

Content type
application/json
{
  • "data": "b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84"
}

Attach a guardrail to models

path Parameters
guardrailsId
required
string
Example: b2c8f4a6-71d3-4e95-8f02-6a1b9c3e7d84

Guardrail id. Obtain from GET /v1/guardrails

Request Body schema: application/json
modelUuids
required
Array of strings

REPLACES the whole set of models. Send [] to detach the guardrail from every model. Obtain from GET /v1/models.

Responses

Request samples

Content type
application/json
{
  • "modelUuids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "API key name already exists."
}

Log

Search the history of requests you have sent to models.

Search request logs

Requests you have sent to models, with filtering and pagination.

Request Body schema: application/json
page
integer

Page number, starting at 1. Send together with size

size
integer

Items per page. Send together with page

from
integer <int64>

Start of range, epoch milliseconds

to
integer <int64>

End of range, epoch milliseconds

searchFullText
string

Full-text search across the log record. Leave empty to skip keyword filtering

minCode
integer

Lowest HTTP status code to include

maxCode
integer

Highest HTTP status code to include

modelUuids
string

Model UUIDs, comma-separated. Obtain from GET /v1/models.

apiKeyIds
string

Key ids, comma-separated. Obtain from GET /v1/api-keys.

providers
string

Provider codes, comma-separated. Obtain from GET /v1/models/metadata.

aggregationType
string
Enum: "value_count" "sum"

How to aggregate. value_count counts requests; sum adds up the values of aggregationField

aggregationField
string

Numeric field to sum. Only used when aggregationType is sum; ignored for value_count. Supported fields: ai.proxy.usage.total_tokens, ai.proxy.usage.prompt_tokens, ai.proxy.usage.completion_tokens, ai.proxy.usage.prompt_cached_tokens

calendarInterval
string
Enum: "minute" "hour" "day" "week" "month" "quarter" "year"

Time bucket size. Required for /v1/models/logs-chart

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "size": 20,
  • "from": 1790787600000,
  • "to": 1793466000000,
  • "minCode": 200,
  • "maxCode": 399
}

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Search request logs for one model

path Parameters
modelUuid
required
string
Example: 8f14e45f-ceea-467a-9c1f-4b1c3a6d2e90

Model UUID. Obtain from GET /v1/models (field uuid)

Request Body schema: application/json
page
integer

Page number, starting at 1. Send together with size

size
integer

Items per page. Send together with page

from
integer <int64>

Start of range, epoch milliseconds

to
integer <int64>

End of range, epoch milliseconds

searchFullText
string

Full-text search across the log record. Leave empty to skip keyword filtering

minCode
integer

Lowest HTTP status code to include

maxCode
integer

Highest HTTP status code to include

modelUuids
string

Model UUIDs, comma-separated. Obtain from GET /v1/models.

apiKeyIds
string

Key ids, comma-separated. Obtain from GET /v1/api-keys.

providers
string

Provider codes, comma-separated. Obtain from GET /v1/models/metadata.

aggregationType
string
Enum: "value_count" "sum"

How to aggregate. value_count counts requests; sum adds up the values of aggregationField

aggregationField
string

Numeric field to sum. Only used when aggregationType is sum; ignored for value_count. Supported fields: ai.proxy.usage.total_tokens, ai.proxy.usage.prompt_tokens, ai.proxy.usage.completion_tokens, ai.proxy.usage.prompt_cached_tokens

calendarInterval
string
Enum: "minute" "hour" "day" "week" "month" "quarter" "year"

Time bucket size. Required for /v1/models/logs-chart

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "size": 20,
  • "from": 1790787600000,
  • "to": 1793466000000,
  • "minCode": 200,
  • "maxCode": 399
}

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}

Search request logs as a time series

Figures aggregated into time buckets, for charting.

Request Body schema: application/json
page
integer

Page number, starting at 1. Send together with size

size
integer

Items per page. Send together with page

from
integer <int64>

Start of range, epoch milliseconds

to
integer <int64>

End of range, epoch milliseconds

searchFullText
string

Full-text search across the log record. Leave empty to skip keyword filtering

minCode
integer

Lowest HTTP status code to include

maxCode
integer

Highest HTTP status code to include

modelUuids
string

Model UUIDs, comma-separated. Obtain from GET /v1/models.

apiKeyIds
string

Key ids, comma-separated. Obtain from GET /v1/api-keys.

providers
string

Provider codes, comma-separated. Obtain from GET /v1/models/metadata.

aggregationType
string
Enum: "value_count" "sum"

How to aggregate. value_count counts requests; sum adds up the values of aggregationField

aggregationField
string

Numeric field to sum. Only used when aggregationType is sum; ignored for value_count. Supported fields: ai.proxy.usage.total_tokens, ai.proxy.usage.prompt_tokens, ai.proxy.usage.completion_tokens, ai.proxy.usage.prompt_cached_tokens

calendarInterval
string
Enum: "minute" "hour" "day" "week" "month" "quarter" "year"

Time bucket size. Required for /v1/models/logs-chart

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "size": 20,
  • "from": 1790787600000,
  • "to": 1793466000000,
  • "minCode": 200,
  • "maxCode": 399
}

Response samples

Content type
application/json
{
  • "listData": [
    ],
  • "page": 1,
  • "pageSize": 20,
  • "totalPage": 1,
  • "totalItem": 1
}