This guide describes the APIs provided by NHN Cloud Foundry.
| API | Description |
|---|---|
| Ingest API | Collects data into an existing Data Source. Provides snapshot file upload, event collection, and metric collection. |
| Recommendation API | Requests recommendation results from a created Recommendation System App. |
| Recommendation Event API | Collects user reaction events on recommendation results. |
The API provides two versions: v2.0 and v1.0. Both versions share the same request format (headers and request body) and the same body in success responses. They differ in HTTP status codes and result codes on failure.
| Version | Request Path | Status | Response Specification |
|---|---|---|---|
| v2.0 | /api/v2.0/... |
Current version | HTTP status code 200 for both success and failure. Returns a 7-digit negative result code on failure. |
| v1.0 | /api/v1.0/... |
Scheduled for discontinuation | HTTP status code varies depending on the API and error. Returns a positive result code on failure. |
It is recommended to use v2.0. The end-of-support schedule for v1.0 will be announced separately.
v2.0 responds with HTTP status code 200 for both success and failure. The cause of failure is indicated by a 7-digit negative result code. The request format is the same as v1.0.
To use the API, you need an Appkey and an authentication token.
X-NHN-Authorization header), see the User Access Key Token guide.Required headers:
X-NC-APP-KEY: {appKey}
X-NHN-Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
Base URL:
https://{gateway-public-host}/api/v2.0
All APIs respond with HTTP status code 200, and the response body consists of header and body. Even when a request is rejected or processing fails, the HTTP status code is 200. Therefore, success or failure must be determined by header.isSuccessful, not by the HTTP status code.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {}
}
| Field | Type | Description |
|---|---|---|
| header.isSuccessful | Boolean | Whether the request succeeded. Returns false on failure. |
| header.resultCode | Integer | Result code. 0 on success, a negative error code on failure. |
| header.resultMessage | String | Result message. SUCCESS on success, the error cause on failure. |
| body | Object/Array | Response data per API. Returns null on failure. |
Example of a failure response:
{
"header": {
"isSuccessful": false,
"resultCode": -4041102,
"resultMessage": "IngestJob not found."
},
"body": null
}
Error codes common to all APIs are listed in Common Error Codes below. API-specific error codes are listed in the Error Codes section at the end of each API section.
200.200 and the response body may differ from the format above. This case is also treated as a failure.Caution
If you determine success or failure based on the HTTP status code, failure responses may be treated as success. Clients must always use header.isSuccessful to determine success or failure, and use header.resultCode to identify the cause of failure.
These are error codes that can be returned by all APIs. For API-specific error codes, see the Error Codes section at the end of each API section.
The first three digits of an error code correspond to the HTTP status code. 400-series codes indicate a problem with the request — check the resultMessage, correct the request, and send it again. 500-series codes indicate a service-side issue — retry the same request after a moment, and if it continues to fail, contact the customer support center.
| Code | Message | Description |
|---|---|---|
| -4010000 | Unauthorized | Authentication failed. The authentication token is missing, malformed, or expired, or the Appkey indicated by the token does not match the request target. Reissue the token and retry the request. |
| -4040000 | Not Found | The request path does not exist. Check the URI. |
| -4050000 | Method Not Allowed | The path is correct, but the HTTP method is incorrect. |
| -4150000 | Unsupported Media Type | The Content-Type of the request body is not supported. Send the request with application/json. |
| -5000000 | Internal Server Error | An internal server error occurred. Retry after a moment, and if the issue persists, contact the customer support center. |
| -5030101 | Authentication service is not ready. Please retry. | The authentication service is not ready. Retry after a moment. |
The Ingest API loads data into a Data Source that has already been created in the Console. The following methods are available for each Data Source type:
| Method | Target Data Source | Description |
|---|---|---|
| Snapshot Upload | File | Replaces all data with the uploaded file. |
| Event Collection | File | Adds change events one by one while retaining existing data. |
| Metric Collection | Prometheus API | Sends metric (time-series) data in real time. |
Caution
No API is provided for creating a new Data Source. To use the Ingest API, you must first create a Data Source in the Console.
Replaces all data in the Data Source with the contents of the uploaded file. The upload process consists of three steps.
Caution
Snapshot upload replaces all data currently stored in the Data Source. Existing data cannot be recovered.
Upload limits:
100 MB or less → Single Upload (SINGLE)100 MB → Multipart Upload (MULTIPART)formPost fields exactly as-is in the request.| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/init |
Issues a signed temporary URL for uploading large files directly to storage. Returns either a single URL (SINGLE) or multipart URLs (MULTIPART) depending on the file size.
curl example:
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/init" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"fileName": "data.csv",
"fileSize": 52428800,
"contentType": "text/csv"
}'
| Field | Type | Required | Description |
|---|---|---|---|
| fileName | String | O | File name. Allowed characters: letters, numbers, period (.), underscore (_), hyphen (-) |
| fileSize | Long | O | File size (bytes). Minimum 1, maximum 10 GB |
| contentType | String | X | Content-Type (default: application/octet-stream) |
Response example (SINGLE):
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"uploadType": "SINGLE",
"uploadUrl": "{upload-url}",
"uploadId": null,
"partSize": null,
"parts": null,
"expiresAt": "2025-01-20T11:00:00Z",
"formPost": {
"objectPrefix": "{appKey}/{dataSourceId}/snapshot/{jobId}/",
"signature": "{SIGNATURE}",
"expires": 1737370800,
"maxFileSize": 10737418240,
"maxFileCount": 1
}
}
}
Response example (MULTIPART):
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"uploadType": "MULTIPART",
"uploadUrl": null,
"uploadId": "{appKey}/{dataSourceId}/snapshot/{jobId}/data.csv_segments/",
"partSize": 104857600,
"parts": [
{
"partNumber": 1,
"uploadUrl": "{part-upload-url}?signature={SIG}&expires={TS}&max_file_size=104857600&max_file_count=1",
"headUrl": "{part-head-url}?temp_url_sig={SIG}&temp_url_expires={TS}"
}
],
"expiresAt": "2025-01-20T11:00:00Z",
"formPost": {
"objectPrefix": "{appKey}/{dataSourceId}/snapshot/{jobId}/",
"signature": "{SIGNATURE}",
"expires": 1737370800,
"maxFileSize": 104857600,
"maxFileCount": 1
}
}
}
Note
The formPost field is also included in a MULTIPART response. However, for multipart uploads, parts are sent using the query parameters (signature/expires/max_file_size/max_file_count) from parts[].uploadUrl, so formPost is for reference only and is not used for the part upload itself.
| Field | Description |
|---|---|
| body.jobId | Job ID. Used in subsequent complete/status query requests |
| body.uploadType | Upload type. SINGLE (100 MB or less) or MULTIPART (over 100 MB) |
| body.uploadUrl | Upload URL (for single upload) |
| body.uploadId | Multipart upload ID (for multipart upload) |
| body.partSize | Part size (bytes, for multipart upload) |
| body.parts[].partNumber | Part number (starting from 1) |
| body.parts[].uploadUrl | Part upload URL |
| body.parts[].headUrl | URL for retrieving ETag (HEAD request after upload completes) |
| body.expiresAt | URL expiration time |
| body.formPost.objectPrefix | Object prefix (path prepended to the file name) |
| body.formPost.signature | HMAC-SHA1 signature |
| body.formPost.expires | Expiration time (UNIX timestamp) |
| body.formPost.maxFileSize | Maximum file size (bytes) |
| body.formPost.maxFileCount | Maximum file count |
Send a multipart/form-data POST request to the uploadUrl from the init response.
This request is sent directly to Object Storage, so no additional authentication is required (the signature serves as authentication).
curl example:
curl -X POST "{uploadUrl}" \
-F "redirect=" \
-F "max_file_size={formPost.maxFileSize}" \
-F "max_file_count={formPost.maxFileCount}" \
-F "expires={formPost.expires}" \
-F "signature={formPost.signature}" \
-F "file=@./data.csv;filename=data.csv"
Caution
The file field must be added last in the form data. On success, an HTTP 201 Created response is returned.
Use the parts[] array from the response to upload each part individually.
Each part is processed in the following order: (1) upload → (2) retrieve ETag via HEAD → (3) collect into partETags[] in ascending partNumber order.
partSize (default: 100 MB).signature, expires, max_file_size, max_file_count) from parts[i].uploadUrl and send the part as multipart/form-data (field name: file, fixed file name: part).HEAD request to parts[i].headUrl to collect the ETag value from the response header.partETags array in ascending partNumber order and include it in the complete upload request.Part upload curl example:
# 1) Upload
curl -X POST "{parts[i].uploadUrl}" \
-F "redirect=" \
-F "max_file_size={max_file_size-from-query}" \
-F "max_file_count={max_file_count-from-query}" \
-F "expires={expires-from-query}" \
-F "signature={signature-from-query}" \
-F "file=@./part_i.bin;filename=part"
# 2) Retrieve ETag
curl -I "{parts[i].headUrl}" | grep -i '^etag:'
| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/complete |
curl example (single upload):
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/complete" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "data.csv"
}'
curl example (multipart upload):
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/complete" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "data.csv",
"uploadId": "{multipart-upload-id}",
"partETags": ["etag-part1", "etag-part2", "etag-part3"]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| jobId | String | O | Job ID (the jobId from the init response) |
| fileName | String | O | File name |
| uploadId | String | X | Multipart upload ID (required only for multipart upload) |
| partETags | Array | X | List of ETags per part (required only for multipart upload, in partNumber order) |
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000"
}
}
| Field | Description |
|---|---|
| body.jobId | Job ID. Used for View Job Status |
| Method | URI |
|---|---|
| DELETE | /api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId} |
curl example (single upload):
curl -X DELETE "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
curl example (multipart upload):
Pass uploadId as a query parameter.
curl -X DELETE "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId}?uploadId={uploadId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
| Method | URI |
|---|---|
| GET | /api/v2.0/data-sources/{dataSourceId}/ingest/jobs/{jobId} |
curl example:
curl "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/jobs/{jobId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"dataSourceId": "ds-001",
"jobType": "SNAPSHOT",
"status": "COMPLETED",
"obsFilePath": "s3a://{bucket}/{path}/file.csv",
"statistics": {
"totalRecords": 10000,
"failedRecords": 5,
"successfulRecords": 9995,
"successRate": 0.9995
},
"errorMessage": null,
"createdDatetime": "2025-01-20T10:00:00Z",
"startedDatetime": "2025-01-20T10:01:00Z",
"completedDatetime": "2025-01-20T10:05:00Z",
"modifiedDatetime": "2025-01-20T10:05:00Z"
}
}
| Field | Description |
|---|---|
| body.jobId | Job ID |
| body.dataSourceId | Target Data Source ID |
| body.jobType | Job type. SNAPSHOT (snapshot ingestion) or EVENT (change event) |
| body.status | Job status. See status values below. |
| body.obsFilePath | OBS file path |
| body.statistics.totalRecords | Total record count |
| body.statistics.failedRecords | Failed record count |
| body.statistics.successfulRecords | Successful record count |
| body.statistics.successRate | Success rate (0.0 to 1.0) |
| body.errorMessage | Error message (on failure) |
| body.createdDatetime | Job creation time |
| body.startedDatetime | Job start time |
| body.completedDatetime | Job completion time |
| body.modifiedDatetime | Last modified time |
The job status (status) can have the following values:
| Value | Description |
|---|---|
| UPLOADING | File upload in progress |
| QUEUED | Upload complete, pending ingestion |
| STAGED | Ready for processing |
| RUNNING | Data ingestion in progress |
| COMPLETED | Job completed successfully |
| FAILED | Job failed |
Sends change events while retaining existing data. This is used with file-type data sources, and the Event API must be enabled first. You can enable it from the Event Settings tab in the console or by using the Enable API below.
Caution
Enabling the Event API blocks snapshot uploads. Additionally, schema changes are restricted, so you must disable the Event API before modifying the schema. For instructions on enabling and disabling, refer to 'Event Settings' in the Console User Guide.
| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/events/enable |
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/events/disable |
curl example:
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/events/enable" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"enabled": false,
"status": "ENABLING"
}
}
| Field | Description |
|---|---|
| body.enabled | Whether event ingestion is possible |
| body.status | Activation status. DISABLED, ENABLING, ENABLED, ENABLE_FAILED |
enabled as false and status as ENABLING. Events are collected after the status becomes ENABLED.ENABLING), the request will be rejected. You can check the progress on the Event Settings tab in the console.| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/events |
curl example:
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/events" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"operation": "INSERT",
"data": {
"userId": "user-12345",
"courseId": "course-java-101",
"action": "enroll",
"rating": 4.5
},
"eventTimestamp": "2026-08-25T10:30:00Z"
}'
| Field | Type | Required | Description |
|---|---|---|---|
| operation | String | O | Operation type. One of INSERT, UPDATE, DELETE |
| data | Object | O | Event data. Uses field names from the data source schema as keys |
| eventTimestamp | String | X | Time of the event occurrence. If omitted, the server receipt time is used |
operation is case-insensitive. Sending an unsupported value will result in the request being rejected.INSERT can be sent. UPDATE and DELETE will be rejected. Data sources with a primary key specified can use all three operations.Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"eventId": "evt-550e8400-e29b-41d4-a716-446655440000",
"success": true,
"errorMessage": null
}
}
| Field | Description |
|---|---|
| body.eventId | Event ID |
| body.success | Whether the request succeeded |
| body.errorMessage | Error message on failure |
| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/events/batch |
Sends multiple change events in a single request. Up to 5,000 events can be sent per request.
curl example:
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/events/batch" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"operation": "INSERT",
"data": { "hostname": "server-01", "portName": "eth0", "trafficIn": 1024.5 },
"eventTimestamp": "2026-08-25T10:30:00Z"
},
{
"operation": "UPDATE",
"data": { "hostname": "server-01", "portName": "eth1", "trafficIn": 2048.7 }
}
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| events | Array | O | List of events. Up to 5,000 per request; each item's fields are the same as for a single event |
The body of the response is an array of processing results for each event.
Sends metric data to a data source of type Prometheus API. The transmitted metrics can be viewed in the Analysis menu, and can also be used as input for the Univariate Time-Series Anomaly Detection App.
| Method | URI |
|---|---|
| POST | /api/v2.0/data-sources/{dataSourceId}/ingest/metrics |
curl example:
curl -X POST "https://{gateway-public-host}/api/v2.0/data-sources/{dataSourceId}/ingest/metrics" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"metrics": [
{
"timestamp": 1776149886528,
"value": 4.99,
"labels": [
{ "name": "__name__", "value": "cpu_usage" },
{ "name": "instance_id", "value": "instance-001" }
],
"metadata": { "resourceType": "Instance" }
}
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| metrics | Array | O | Metric list. Cannot be empty; maximum 5,000 items per request. |
| metrics[].timestamp | Long | O | Metric timestamp. Millisecond epoch. |
| metrics[].value | Double | O | Measurement value. |
| metrics[].labels | Array | O | Label list. The combination of labels determines the time series, and Group Labels determine the group. |
| metrics[].labels[].name | String | O | Label name. Must start with a letter or underscore (_), and can only contain letters, numbers, and underscores. |
| metrics[].labels[].value | String | O | Label value. Commas and equal signs cannot be used. |
| metrics[].metadata | Object | X | Additional information. Stored and forwarded as-is without interpretation. The identityKey key is reserved for system use and cannot be used. |
If successful, header.isSuccessful returns true and there is no body. If the request is rejected, header.isSuccessful returns false, so use header to determine whether the request succeeded.
The collection rules are as follows:
timestamp is an epoch in milliseconds. If sent in seconds, it will be stored as an incorrect time.value is NaN or Infinity are skipped and not stored. The remaining items in the same request are processed normally.Note
Ingestion is independent of the transmission interval. However, if this Data Source is connected to the Univariate Time-Series Anomaly Detection App, you must send data for the same time series continuously, one per minute. Since the App groups metrics in 1-minute units to make determinations, sending at longer intervals creates gaps that may prevent completion of preparation in accurate mode. Training also has requirements. If the Data Source contains only one time series, training will fail, so you must have at least two time series. Each time series must accumulate data continuously for approximately 4 hours or more to train correctly.
These are error codes that can be returned across all Ingest APIs in addition to the common error codes.
| Code | Message | Description |
|---|---|---|
| -4000001 | Invalid request. | Request format error. Missing required fields, range or format violations for values, request body JSON parsing failure, or missing X-NC-APP-KEY header. |
| -4041101 | DataSource not found. | The data source for the specified dataSourceId does not exist, or belongs to a different Appkey. |
| Code | Message | Description | Target API |
|---|---|---|---|
| -4000202 | Invalid file name. | fileName is empty or contains characters other than letters, digits, ., _, and -. |
init, complete |
| -4001107 | File size exceeds maximum limit. | fileSize exceeds 10 GB. |
init |
| -4001101 | Invalid data source type. | The data source is not of file type. | init |
| -4001103 | DataSource is busy. | Cannot upload a snapshot because the data source is loading data or the Event API is enabled. | init, complete |
| -4001104 | Ingest job is already running. | There is already a snapshot upload job in progress for the same data source. Wait for it to complete or be canceled, then try again. | init, complete |
| -4000201 | DataSource is not ready for ingest. | The data source is not in a state where it can start loading. | complete |
| -4041102 | IngestJob not found. | The job for the specified jobId does not exist, or belongs to a different Appkey. |
complete, Cancel Upload, View Job Status |
| -4001105 | IngestJob is in invalid status. | The job is not in an uploading state. It has already completed, been canceled, or failed due to the upload time limit expiring. Start again from init. | complete |
| -4000203 | File name does not match. | The fileName does not match the one sent during init. |
complete |
| -4291101 | Too many requests. Please try again later. | Too many jobs are waiting to be processed and the request cannot be accepted. Try again later. | init, complete |
| Code | Message | Description | Target API |
|---|---|---|---|
| -4001101 | Invalid data source type. | The data source is not of file type. | Enable, Disable |
| -4000201 | DataSource is not ready for ingest. | The data source is not in a state where it can receive events. This may occur when a snapshot load is in progress. | Enable, Single Send, Batch Send |
| -4001104 | Ingest job is already running. | Cannot enable because a snapshot upload job is in progress. | Enable |
| -4091103 | Stream API activation is in progress. Please wait. | Activation is in progress. Wait for it to complete. | Enable |
| -4091601 | Operation is in progress. Please wait for the current operation to complete. | Another operation is in progress for the same data source. Try again after it completes. | Enable |
| -4000002 | Invalid strategy type. | The data source type does not support event collection. | Single Send, Batch Send |
| -4001109 | Stream API is not enabled. | The Event API is not enabled. Call the Enable API first. | Single Send, Batch Send |
| -4000204 | Invalid operation. | operation is not INSERT, UPDATE, or DELETE, or an operation other than INSERT was sent for a data source that has no primary key. |
Single Send |
| -5004001 | Failed to serialize Kafka message. | Failed to convert the event to the storage format. | Single Send |
| -5004002 | Kafka send timeout. | Event storage did not complete within the timeout period. Try again later. | Single Send |
| -5004003 | Kafka send failed. | Failed to store the event. Try again later. | Single Send |
| -5004004 | Kafka send interrupted. | Event storage was interrupted. Try again later. | Single Send |
In Batch Send, per-item errors are returned in body[].success and body[].errorMessage, not in header. If data source validation fails, the entire request is rejected with one of the codes above.
| Code | Message | Description |
|---|---|---|
| -4000001 | Invalid request. | metrics is empty, exceeds 5,000 items, or is missing timestamp, value, or labels; a label name or value rule is violated; or the X-NC-APP-KEY header is missing. The entire request is rejected. |
| -4000002 | Invalid strategy type. | The data source type does not support metric collection. |
| -4000201 | DataSource is not ready for ingest. | The data source is not in a state where it can receive metrics. |
| -5004001 | Failed to serialize Kafka message. | Failed to convert the metric to the storage format. |
| -5004004 | Kafka send interrupted. | Metric storage was interrupted. Try again later. |
| -5004005 | Kafka batch send partially failed. | Some metrics failed to be stored or exceeded the timeout period. Resending the request may result in duplicate metrics that were already stored. |
Enables, disables, and deletes groups in the Univariate Time-Series Anomaly Detection app. All three APIs share the same request format, but differ only in the path.
| Method | URI |
|---|---|
| POST | /api/v2.0/serving-pipelines/{servingPipelineId}/groups/enable |
| POST | /api/v2.0/serving-pipelines/{servingPipelineId}/groups/disable |
| POST | /api/v2.0/serving-pipelines/{servingPipelineId}/groups/delete |
servingPipelineId is the app ID displayed in the Console app details.
curl Example:
curl -X POST "https://{gateway-public-host}/api/v2.0/serving-pipelines/{servingPipelineId}/groups/enable" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"groupKey": [
{ "name": "region", "value": ["kr1", "jp1"] }
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| groupKey | Array | Conditional | List of labels that specify the target group. Used only when group labels are specified in the Data Source. |
| groupKey[].name | String | O | Group Label name. Must exactly match the group label name specified in the Data Source. |
| groupKey[].value | Array | O | List of values for that label. Each value corresponds to one group. |
On success, header.isSuccessful returns true, and there is no body.
The request rules are as follows:
groupKey. The entire Data Source is treated as a single group, which becomes the target. Sending groupKey along with the request will result in the request being rejected.groupKey is required. The set of label names sent must exactly match the group labels in the Data Source. Sending the same label name twice will result in rejection.["a", "b"] for rule_id and ["q", "w"] for instance_id, the two target groups are (a, q) and (b, w). The number of values for all labels must be equal; if they differ, the request is rejected.Note
If no group labels are specified in the Data Source, the entire Data Source is registered as a single group when the app is created, so the app works without using this API. If group labels are specified, groups are not registered automatically, so you must register the target groups using the enable API to receive detection results. This operation is available through the API only. You can check registered groups and their statuses on the Group List tab in the Console app details.
Caution
Disabling a group does not stop the transmission of detection results. Only the status displayed in the group list changes to inactive. A deleted group disappears along with its status history and cannot be recovered.
The following error codes may be returned by the Enable, Disable, and Delete Groups API, in addition to the common error codes.
| Code | Message | Description | Target API |
|---|---|---|---|
| -4000001 | Invalid request. | Violation of groupKey rules: sent groupKey to a Data Source with no group labels, required groupKey is missing, the set of label names does not match the group labels in the Data Source, duplicate label names, value list is empty, or value counts differ. Missing X-NC-APP-KEY header. |
Enable, Disable, Delete |
| -4041301 | ServingPipeline not found. | No app exists for the specified servingPipelineId, or the app belongs to a different Appkey. |
Enable, Disable, Delete |
| -4041101 | DataSource not found. | The Metric Data Source connected to the app cannot be found. | Enable, Disable, Delete |
| -4000201 | DataSource is not ready for ingest. | The Metric Data Source is not in a usable state. | Enable, Disable, Delete |
| -4001302 | Serving pipeline is not active. | The app is not in an active state. Try again after the app status becomes active. | Enable |
| -4041306 | Group entry not found or has no trainingPipelineId. | One or more groups in the request are not registered. Other groups included in the request are also not processed. | Disable, Delete |
Requests recommendation results from the Recommendation System App. If a user has sufficient history, the server uses model-based (Sequential) inference; otherwise, it uses attribute-based (Cold Start) inference.
| Method | URI |
|---|---|
| POST | /api/v2.0/recommendation-apps/{appId}/recommend |
curl Example:
curl -X POST "https://{gateway-public-host}/api/v2.0/recommendation-apps/{appId}/recommend" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_12345",
"context": {
"currentItemKey": "CONT0001",
"recentlyViewed": ["CONT0010", "CONT0023"],
"pageType": "course_detail",
"sessionId": "session_abc123"
},
"options": {
"maxRecommendations": 10
}
}'
| Field | Type | Required | Description |
|---|---|---|---|
| userId | String | O | User ID to receive recommendations. To request recommendations for an anonymous user, specify an empty string (""). |
| context.currentItemKey | String | X | Key of the item currently being viewed |
| context.recentlyViewed | Array | X | List of recently viewed item keys |
| context.availableItems | Array | X | List of item keys available for recommendation. If specified, only items in this list are recommended. |
| context.pageType | String | X | Current page type (free-form; e.g., home, item_detail) |
| context.sessionId | String | X | Session ID |
| context.impressions | Array | X | List of items exposed to the user as recommendation results |
| context.interactions | Array | X | User's item interaction information |
| context.feedback | Array | X | Ratings that the user left on items |
| userAttributes | Object | X | User attribute information (used for Cold Start inference) |
| options.maxRecommendations | Integer | X | Maximum number of recommendations (from 1 to 100). Values exceeding 100 are adjusted to 100 without an error; if not specified, 100 is applied. If fewer items are available than this value, only the actual number of items is returned. |
| options.mode | String | X | Specifies the inference method. One of sequential (history-based), cold_start (attribute-based), or popular (popularity-based). Other values are rejected. If not specified, the server determines the method automatically. |
| options.longtail | Boolean | X | Improves recommendation diversity by including less popular items. Applies only when sequential is used. |
| options.excludeItemKeys | Array | X | List of item keys to exclude from recommendations. Excluded items are not counted in the maximum recommendation count. |
options.mode is not specified, the server determines the inference method. If a model for the determined method is not linked to the app, recommendations are made using another method linked to the app instead. The method actually used can be checked in body.metadata.inferenceType in the response.options.mode, the request is rejected with result code -4004201. Even if the value is valid, if the model for the requested method is not linked to the app and no alternative method is available, result code -5034201 is returned. Check which models are available in the app and whether training has completed, then retry. Requests that specify a method via options.mode are not substituted, so you may receive this response.context.impressions is used to re-rank recommendation results based on the recommendation information exposed to the user.
context.interactions and context.feedback are fields that convey the actions that the user took on recommendation results, and incorporate user behavior data into model inference.
{
"userId": "user_12345",
"context": {
"impressions": [
{
"requestId": "req_xyz789",
"itemKeys": ["CONT0023", "CONT0045"],
"occurredAt": "2026-08-25T10:00:00+09:00"
}
],
"interactions": [
{
"requestId": "req_xyz789",
"itemKey": "CONT0023",
"type": "CLICK",
"occurredAt": "2026-08-25T10:00:05+09:00"
}
],
"feedback": [
{
"requestId": "req_xyz789",
"itemKey": "CONT0045",
"type": "NEGATIVE",
"occurredAt": "2026-08-25T10:00:10+09:00"
}
]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
| requestId | String | O | body.metadata.requestId of the recommendation response in which the action occurred |
| itemKeys | Array | O | List of exposed item keys. Enter in order of exposure; used in impressions. |
| itemKey | String | O | Target item key. Used in interactions and feedback. |
| type | String | O | For interactions: CLICK or CONVERSION. For feedback: POSITIVE or NEGATIVE. |
| occurredAt | String | O | Time when the action occurred |
occurredAt in ISO 8601 format with a timezone offset. Requests without an offset are treated as errors.requestId, occurredAt, and the item key — must be present for the signal to be used.impressions allows up to 10 entries, with up to 100 itemKeys per entry. interactions and feedback allow up to 10 entries per type. Requests that exceed these limits are rejected.feedback for the same item changes, only the most recent value is reflected, so resend it with each request to maintain its effect.Note
The userAttributes schema's collection method and field types may change in the future based on the implementation direction of Preference Elicitation.
Response Example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"userId": "user_12345",
"recommendations": [
{ "itemKey": "CONT0023", "score": 0.95, "position": 1 },
{ "itemKey": "CONT0045", "score": 0.89, "position": 2 }
],
"metadata": {
"modelVersion": "v1.2.0",
"requestId": "req_xyz789",
"inferenceType": "sequential",
"abTestGroup": ""
}
}
}
| Field | Description |
|---|---|
| body.userId | User ID of the requester |
| body.recommendations[].itemKey | Recommended item key |
| body.recommendations[].score | Recommendation score (from 0.0 to 1.0) |
| body.recommendations[].position | Recommendation ranking |
| body.metadata.modelVersion | Version of the model used |
| body.metadata.requestId | Request tracking ID. Use this value when sending to the Recommendation Event API. |
| body.metadata.inferenceType | Inference type: sequential (history-based), cold_start (attribute-based), or popular (popularity-based) |
| body.metadata.abTestGroup | A/B test group (currently returns an empty value) |
The following error codes may be returned from recommendation requests in addition to the common error codes.
| Code | Message | Description |
|---|---|---|
| -4004201 | Invalid request. or rejection reason | Request format error. Causes include: missing userId, maxRecommendations less than 1, invalid value for options.mode, violation of the minimum recommendation count rule for a category, a category not found in the catalog, violation of behavior signal format or count in context, missing X-NC-APP-KEY header, etc. The resultMessage includes the rejection reason. |
| -4044201 | Recommendation app not found. | No recommendation app corresponding to appId exists, or the X-NC-APP-KEY does not match the app. |
| -4001301 | Invalid model type. | appId does not correspond to a Recommendation System App. |
| -4001302 | Serving pipeline is not active. | The app is not in an active state. Retry after the app status becomes active. |
| -5034201 | Recommendation model is not ready. | The model for the requested recommendation mode is not yet linked to the app. Retry after the initial training and deployment are complete. |
Collects events representing user reactions (such as clicks) to recommendation results. You can analyze recommendation success rates using the collected event data.
| Method | URI |
|---|---|
| POST | /api/v2.0/recommendation-apps/{appId}/events |
curl Example:
curl -X POST "https://{gateway-public-host}/api/v2.0/recommendation-apps/{appId}/events" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"eventType": "CLICK",
"requestId": "req_xyz789",
"itemKey": "CONT0023",
"userId": "user_12345",
"context": {
"sessionId": "sess_abc",
"placement": "home_main"
}
}'
Pass the values of requestId, itemKey, and userId exactly as received from the recommendation API response.
| Field | Required | Description |
|---|---|---|
| eventType | O | Event type. Freely definable (e.g., CLICK, PURCHASE, IMPRESSION). Only letters, numbers, and underscores () are allowed (^[A-Za-z0-9]+$), with a maximum of 64 characters. Stored in uppercase regardless of the case used. REQUEST and RESPONSE are reserved words and cannot be used. |
| requestId | O | The body.metadata.requestId value from the recommendation API response (opaque string, up to 128 characters) |
| itemKey | O | The itemKey of the recommended item that the user reacted to |
| userId | X | The body.userId value from the recommendation API response |
| context | X | Additional event information (free-form key-value pairs, e.g., exposure position, placement) |
| userAttributes | X | User attribute information (free-form key-value pairs) |
| options | X | Additional options (free-form key-value pairs) |
A successful response (200) returns only the header.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
}
}
Note
These are error codes that can be returned when sending recommendation events, in addition to the common error codes.
| Code | Message | Description |
|---|---|---|
| -4004202 | Invalid event request. | Invalid request format. Returned when eventType is empty, exceeds 64 characters, contains characters other than letters, numbers, or _, or is a reserved word (REQUEST, RESPONSE); when requestId is empty or exceeds 128 characters; when itemKey is missing; or when required headers are missing. |
| -4044201 | Recommendation app not found. | No recommendation app matching the appId was found, or the app does not match the X-NC-APP-KEY. |
| -4001301 | Invalid model type. | The appId does not correspond to a Recommendation System app. |
| -4001302 | Serving pipeline is not active. | The app is not in an active state. |
| -4094201 | Recommendation event dataset is not configured for this app. | No Data Source is configured to store recommendation events for the app. |
| -5034202 | Event publish failed. | Failed to save the event. Try again later. |
| -5044201 | Event publish timed out. | The event was not saved within the time limit. Try again later. |
Caution
API v1.0 is scheduled for end of support. The end-of-support schedule will be announced separately. It is recommended to use v2.0. For more information, see API v2.0 Guide.
To use the API, you need an Appkey and an authentication token.
X-NHN-Authorization header), refer to the User Access Key Token guide.Required headers:
X-NC-APP-KEY: {appKey}
X-NHN-Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
Base URL:
https://{gateway-public-host}/api/v1.0
All API responses consist of a header and a body.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {}
}
| Field | Type | Description |
|---|---|---|
| header.isSuccessful | Boolean | Whether the request was successful |
| header.resultCode | Integer | Result code. 0 for success, error code for failure |
| header.resultMessage | String | Result message. SUCCESS for success, detailed error message for failure |
| body | Object/Array | Response data per API |
Even if a request is rejected, the HTTP status code may be returned as 200. Success is determined by header.isSuccessful and header.resultCode, not the HTTP status code. If the authentication token is missing or expired, HTTP 401 is returned.
The Ingest API loads data into Data Sources that have already been created in the Console. The following methods are provided based on the Data Source type:
| Method | Target Data Source | Description |
|---|---|---|
| Snapshot Upload | File | Replaces all data with the uploaded file |
| Event Collection | File | Adds change events one by one while retaining existing data |
| Metric Collection | Prometheus API | Sends metric (time-series) data in real time |
Caution
No API is provided for creating new Data Sources. To use the Ingest API, you must first create a Data Source in the Console.
Replaces all data in the Data Source with the contents of the uploaded file. The upload process consists of three steps.
Caution
Snapshot upload replaces all data already loaded in the Data Source. Existing data cannot be recovered.
Upload limits:
100MB or less → Single Upload (SINGLE)100MB → Multipart Upload (MULTIPART)formPost field values exactly as returned in the response.| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/init |
Issues a signed temporary URL for uploading large files directly to storage. Returns a single URL (SINGLE) or a multipart URL (MULTIPART) depending on the file size.
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/init" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"fileName": "data.csv",
"fileSize": 52428800,
"contentType": "text/csv"
}'
| Field | Type | Required | Description |
|---|---|---|---|
| fileName | String | O | File name. Allowed characters: letters, numbers, period (.), underscore (_), hyphen (-) |
| fileSize | Long | O | File size (bytes). Minimum 1, maximum 10 GB |
| contentType | String | X | Content-Type (default: application/octet-stream) |
Response example (SINGLE):
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"uploadType": "SINGLE",
"uploadUrl": "{upload-url}",
"uploadId": null,
"partSize": null,
"parts": null,
"expiresAt": "2025-01-20T11:00:00Z",
"formPost": {
"objectPrefix": "{appKey}/{dataSourceId}/snapshot/{jobId}/",
"signature": "{SIGNATURE}",
"expires": 1737370800,
"maxFileSize": 10737418240,
"maxFileCount": 1
}
}
}
Response example (MULTIPART):
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"uploadType": "MULTIPART",
"uploadUrl": null,
"uploadId": "{appKey}/{dataSourceId}/snapshot/{jobId}/data.csv_segments/",
"partSize": 104857600,
"parts": [
{
"partNumber": 1,
"uploadUrl": "{part-upload-url}?signature={SIG}&expires={TS}&max_file_size=104857600&max_file_count=1",
"headUrl": "{part-head-url}?temp_url_sig={SIG}&temp_url_expires={TS}"
}
],
"expiresAt": "2025-01-20T11:00:00Z",
"formPost": {
"objectPrefix": "{appKey}/{dataSourceId}/snapshot/{jobId}/",
"signature": "{SIGNATURE}",
"expires": 1737370800,
"maxFileSize": 104857600,
"maxFileCount": 1
}
}
}
Note
The MULTIPART response also includes formPost. However, since multipart upload transmits each part using the query parameters (signature/expires/max_file_size/max_file_count) of parts[].uploadUrl, formPost is for reference only and is not used for the actual part upload.
| Field | Description |
|---|---|
| body.jobId | Job ID. Used in subsequent complete/status query requests |
| body.uploadType | Upload type. SINGLE (100 MB or less) or MULTIPART (more than 100 MB) |
| body.uploadUrl | Upload URL (for single upload) |
| body.uploadId | Multipart upload ID (for multipart upload) |
| body.partSize | Part size (bytes, for multipart upload) |
| body.parts[].partNumber | Part number (starting from 1) |
| body.parts[].uploadUrl | Part upload URL |
| body.parts[].headUrl | URL for ETag retrieval (HEAD request after upload completion) |
| body.expiresAt | URL expiration time |
| body.formPost.objectPrefix | Object prefix (path prepended to the file name) |
| body.formPost.signature | HMAC-SHA1 signature |
| body.formPost.expires | Expiration time (UNIX timestamp) |
| body.formPost.maxFileSize | Maximum file size (bytes) |
| body.formPost.maxFileCount | Maximum file count |
Send a multipart/form-data POST request to the uploadUrl from the init response.
This request is sent directly to Object Storage, so no separate authentication is required (the signature serves as authentication).
curl example:
curl -X POST "{uploadUrl}" \
-F "redirect=" \
-F "max_file_size={formPost.maxFileSize}" \
-F "max_file_count={formPost.maxFileCount}" \
-F "expires={formPost.expires}" \
-F "signature={formPost.signature}" \
-F "file=@./data.csv;filename=data.csv"
Caution
The file field must be added last in the form data. On success, you will receive an HTTP 201 Created response.
Receive the parts[] array from the response and upload each part individually.
Each part is processed in the following order: (1) upload → (2) retrieve the ETag via HEAD → (3) collect in partETags[] in ascending partNumber order.
partSize (default 100 MB).signature, expires, max_file_size, max_file_count) from parts[i].uploadUrl and send as multipart/form-data (field name file, fixed file name part).HEAD request to parts[i].headUrl to collect the ETag value from the response header.partETags array in ascending partNumber order and include it in the upload complete request.Part upload curl example:
# 1) Upload
curl -X POST "{parts[i].uploadUrl}" \
-F "redirect=" \
-F "max_file_size={max_file_size-from-query}" \
-F "max_file_count={max_file_count-from-query}" \
-F "expires={expires-from-query}" \
-F "signature={signature-from-query}" \
-F "file=@./part_i.bin;filename=part"
# 2) Retrieve ETag
curl -I "{parts[i].headUrl}" | grep -i '^etag:'
| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/complete |
curl example (single upload):
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/complete" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "data.csv"
}'
curl example (multipart upload):
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/complete" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "data.csv",
"uploadId": "{multipart-upload-id}",
"partETags": ["etag-part1", "etag-part2", "etag-part3"]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| jobId | String | O | Job ID (the jobId from the init response) |
| fileName | String | O | File name |
| uploadId | String | X | Multipart upload ID (required only for multipart upload) |
| partETags | Array | X | List of ETags per part (required only for multipart upload, in partNumber order) |
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000"
}
}
| Field | Description |
|---|---|
| body.jobId | Job ID. Used for View Job Status |
| Method | URI |
|---|---|
| DELETE | /api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId} |
curl example (single upload):
curl -X DELETE "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
curl example (multipart upload):
Pass uploadId as a query parameter.
curl -X DELETE "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/snapshots/{jobId}?uploadId={uploadId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
| Method | URI |
|---|---|
| GET | /api/v1.0/data-sources/{dataSourceId}/ingest/jobs/{jobId} |
curl example:
curl "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/jobs/{jobId}" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"dataSourceId": "ds-001",
"jobType": "SNAPSHOT",
"status": "COMPLETED",
"obsFilePath": "s3a://{bucket}/{path}/file.csv",
"statistics": {
"totalRecords": 10000,
"failedRecords": 5,
"successfulRecords": 9995,
"successRate": 0.9995
},
"errorMessage": null,
"createdDatetime": "2025-01-20T10:00:00Z",
"startedDatetime": "2025-01-20T10:01:00Z",
"completedDatetime": "2025-01-20T10:05:00Z",
"modifiedDatetime": "2025-01-20T10:05:00Z"
}
}
| Field | Description |
|---|---|
| body.jobId | Job ID |
| body.dataSourceId | Target Data Source ID |
| body.jobType | Job type. SNAPSHOT (snapshot loading) or EVENT (change event) |
| body.status | Job status. Refer to the status values below |
| body.obsFilePath | OBS file path |
| body.statistics.totalRecords | Total record count |
| body.statistics.failedRecords | Failed record count |
| body.statistics.successfulRecords | Successful record count |
| body.statistics.successRate | Success rate (0.0 to 1.0) |
| body.errorMessage | Error message (on failure) |
| body.createdDatetime | Job creation time |
| body.startedDatetime | Job start time |
| body.completedDatetime | Job completion time |
| body.modifiedDatetime | Last modified time |
The job status (status) has the following values:
| Value | Description |
|---|---|
| UPLOADING | File is being uploaded |
| QUEUED | Upload complete, waiting to be loaded |
| STAGED | Ready for processing |
| RUNNING | Data is being loaded |
| COMPLETED | Job completed successfully |
| FAILED | Job failed |
Sends change events while retaining existing data. This is used with a Data Source whose type is File, and you must enable the Event API first. You can enable it from the event settings tab in the Console or by using the Enable API below.
Caution
Enabling the Event API blocks snapshot uploads. Schema changes are also restricted; to change the Schema, you must disable the Event API first. For information on how to enable and disable it, refer to 'Event Settings' in the Console User Guide.
| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/events/enable |
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/events/disable |
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/events/enable" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}"
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"enabled": false,
"status": "ENABLING"
}
}
| Field | Description |
|---|---|
| body.enabled | Whether events can be collected |
| body.status | Activation status. DISABLED, ENABLING, ENABLED, ENABLE_FAILED |
enabled set to false and status set to ENABLING. Events are collected after the status becomes ENABLED.ENABLING), the request is rejected. You can check the progress in the event settings tab in the Console.| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/events |
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/events" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"operation": "INSERT",
"data": {
"userId": "user-12345",
"courseId": "course-java-101",
"action": "enroll",
"rating": 4.5
},
"eventTimestamp": "2026-08-25T10:30:00Z"
}'
| Field | Type | Required | Description |
|---|---|---|---|
| operation | String | O | Operation type. One of INSERT, UPDATE, DELETE |
| data | Object | O | Event data. Uses the field names from the Data Source Schema as keys |
| eventTimestamp | String | X | Time when the event occurred. If omitted, the Server's received time is used |
operation is case-insensitive. Sending an unsupported value results in the request being rejected.INSERT can be sent. UPDATE and DELETE are rejected. A Data Source with a primary key field specified can use all three operations.Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"eventId": "evt-550e8400-e29b-41d4-a716-446655440000",
"success": true,
"errorMessage": null
}
}
| Field | Description |
|---|---|
| body.eventId | Event ID |
| body.success | Whether the operation was successful |
| body.errorMessage | Error message on failure |
| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/events/batch |
Sends multiple change events at once. Up to 5,000 events can be sent per request.
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/events/batch" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"operation": "INSERT",
"data": { "hostname": "server-01", "portName": "eth0", "trafficIn": 1024.5 },
"eventTimestamp": "2026-08-25T10:30:00Z"
},
{
"operation": "UPDATE",
"data": { "hostname": "server-01", "portName": "eth1", "trafficIn": 2048.7 }
}
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| events | Array | O | Event list. Up to 5,000 events per request; the fields for each item are the same as for single event sending |
The body of the response is an array of processing results for each event.
Sends metric data to a Data Source of the Prometheus API type. The sent metrics can be viewed in the Analysis menu and can also be used as input for the Univariate Time-Series Anomaly Detection App.
| Method | URI |
|---|---|
| POST | /api/v1.0/data-sources/{dataSourceId}/ingest/metrics |
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/data-sources/{dataSourceId}/ingest/metrics" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"metrics": [
{
"timestamp": 1776149886528,
"value": 4.99,
"labels": [
{ "name": "__name__", "value": "cpu_usage" },
{ "name": "instance_id", "value": "instance-001" }
],
"metadata": { "resourceType": "Instance" }
}
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| metrics | Array | O | List of metrics. Cannot be empty; maximum of 5,000 items per request. |
| metrics[].timestamp | Long | O | Metric timestamp. Millisecond epoch. |
| metrics[].value | Double | O | Measured value. |
| metrics[].labels | Array | O | List of labels. The label combination determines the time series, and the Group Label determines the Group. |
| metrics[].labels[].name | String | O | Label name. Must start with a letter or underscore (_) and can only contain letters, numbers, and underscores. |
| metrics[].labels[].value | String | O | Label value. Commas and equals signs cannot be used. |
| metrics[].metadata | Object | X | Additional information. Stored and delivered as-is without interpretation. The identityKey key is reserved for system use and cannot be used. |
On success, HTTP 202 Accepted is returned. If the request is rejected, HTTP 200 is returned with header.isSuccessful set to false. Check the header to determine whether the request succeeded.
The collection rules are as follows:
timestamp is a millisecond-unit epoch. If sent in seconds, the data is stored with an incorrect timestamp.value is NaN or Infinity are skipped and not stored. The remaining items in the same request are processed normally.202 response indicates that the data has been received. Storage is reflected shortly after, and sending the same request again may result in duplicate data being stored.Note
Ingestion is independent of the transmission interval. However, if this Data Source is connected to the Univariate Time-Series Anomaly Detection App, you must send data for the same time series without interruption — one record per minute. Because the App evaluates metrics in 1-minute intervals, sending data at longer intervals creates gaps that may prevent preparation from completing in accurate mode. Training also has requirements. If the Data Source has only one time series, training fails, so there must be at least two time series. Each time series must also accumulate at least approximately 4 hours of uninterrupted data for training to complete successfully.
Enables, stops, and deletes groups in the Univariate Time-Series Anomaly Detection app. The three APIs share the same request format, differing only in the path.
| Method | URI |
|---|---|
| POST | /api/v1.0/serving-pipelines/{servingPipelineId}/groups/enable |
| POST | /api/v1.0/serving-pipelines/{servingPipelineId}/groups/disable |
| POST | /api/v1.0/serving-pipelines/{servingPipelineId}/groups/delete |
servingPipelineId is the app ID displayed in the app Details on the Console.
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/serving-pipelines/{servingPipelineId}/groups/enable" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"groupKey": [
{ "name": "region", "value": ["kr1", "jp1"] }
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
| groupKey | Array | Conditional | List of labels specifying the target groups. Used only when group labels are specified in the Data Source. |
| groupKey[].name | String | O | Group Label name. Must exactly match the name of the group label specified in the Data Source. |
| groupKey[].value | Array | O | List of values for the label. Each value corresponds to one group. |
On success, header.isSuccessful is returned as true and body is empty.
Request rules are as follows:
groupKey. The entire Data Source constitutes a single group, and that group becomes the target. If groupKey is included in the request, the request will be rejected.groupKey is required. The set of label names sent must exactly match the group labels in the Data Source. Sending the same label name twice will result in rejection.["a", "b"] is sent for rule_id and ["q", "w"] for instance_id, the two target groups are (a, q) and (b, w). All labels must have the same number of values; if they differ, the request is rejected.Note
If no group labels are specified in the Data Source, the entire Data Source is registered as a single group when app creation is complete, so this API is not required for operation. If group labels are specified, groups are not registered automatically. You must register the target groups using the Enable API to receive detection results. This operation is available through the API only. Registered groups and their statuses can be checked on the Group List tab in the app Details on the Console.
Caution
Stopping a group does not stop the transmission of detection results. Only the status displayed in the group list changes to Inactive. A deleted group disappears along with its status history and cannot be recovered.
Requests recommendation results from the Recommendation System App that you created. If user history is sufficient, inference uses a model-based approach (Sequential); if insufficient, it uses an attribute-based approach (Cold Start).
| Method | URI |
|---|---|
| POST | /api/v1.0/recommendation-apps/{appId}/recommend |
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/recommendation-apps/{appId}/recommend" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_12345",
"context": {
"currentItemKey": "CONT0001",
"recentlyViewed": ["CONT0010", "CONT0023"],
"pageType": "course_detail",
"sessionId": "session_abc123"
},
"options": {
"maxRecommendations": 10
}
}'
| Field | Type | Required | Description |
|---|---|---|---|
| userId | String | O | User ID of the user to receive recommendations. To request recommendations for an anonymous user, specify an empty string ("") |
| context.currentItemKey | String | X | Key of the item currently being viewed |
| context.recentlyViewed | Array | X | List of recently viewed item keys |
| context.availableItems | Array | X | List of item keys to recommend from. If specified, only items in this list are recommended |
| context.pageType | String | X | Current page type (free format, e.g., home, item_detail) |
| context.sessionId | String | X | Session ID |
| context.impressions | Array | X | List of items exposed to the user as recommendation results |
| context.interactions | Array | X | User's item interaction information |
| context.feedback | Array | X | User's feedback on items |
| userAttributes | Object | X | User attribute information (used for Cold Start inference) |
| options.maxRecommendations | Integer | X | Maximum number of recommendations (from 1 to 100). Values exceeding 100 are adjusted to 100 without an error; defaults to 100 if not specified. If fewer items are available than this value, only the actual number of items is returned |
| options.mode | String | X | Specifies the inference method. One of sequential (history-based), cold_start (attribute-based), or popular (popularity-based). If not specified, the server determines automatically |
| options.longtail | Boolean | X | Improves recommendation diversity by including less popular items. Applies only when sequential is used |
| options.excludeItemKeys | Array | X | List of item keys to exclude from recommendations. Excluded items are not counted toward the maximum number of recommendations |
options.mode is not specified, the server determines the inference method. If the app does not have a model for the determined method, it falls back to another method linked to the app. The method actually used can be checked in body.metadata.inferenceType in the response.503 and result code 5030001 are returned. Check which models are available in the app and whether training is complete, then retry. Requests that specify a method with options.mode do not fall back, so this response may be returned.context.impressions is used to re-rank recommendation results based on the recommendation information exposed to the user.
context.interactions and context.feedback are fields that convey user actions on recommendation results, and reflect user behavior data in model inference.
{
"userId": "user_12345",
"context": {
"impressions": [
{
"requestId": "req_xyz789",
"itemKeys": ["CONT0023", "CONT0045"],
"occurredAt": "2026-08-25T10:00:00+09:00"
}
],
"interactions": [
{
"requestId": "req_xyz789",
"itemKey": "CONT0023",
"type": "CLICK",
"occurredAt": "2026-08-25T10:00:05+09:00"
}
],
"feedback": [
{
"requestId": "req_xyz789",
"itemKey": "CONT0045",
"type": "NEGATIVE",
"occurredAt": "2026-08-25T10:00:10+09:00"
}
]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
| requestId | String | O | body.metadata.requestId of the recommendation response in which the action occurred |
| itemKeys | Array | O | List of exposed item keys. Enter in order of exposure; used in impressions |
| itemKey | String | O | Target item key. Used in interactions and feedback |
| type | String | O | For interactions: CLICK, CONVERSION. For feedback: POSITIVE, NEGATIVE |
| occurredAt | String | O | Time when the action occurred |
occurredAt must be sent in ISO 8601 format with a timezone offset. Requests without an offset are treated as an error.requestId, occurredAt, and the item key — must be present for the data to be used as a signal.impressions supports up to 10 entries, with up to 100 itemKeys per entry. interactions and feedback support up to 10 entries per type. Requests that exceed these limits are rejected.feedback for the same item changes, only the most recent value is reflected, so you must resend on every request to maintain the effect.Note
The userAttributes schema may change in its collection method or field types depending on the future direction of Preference Elicitation implementation.
Response example:
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
},
"body": {
"userId": "user_12345",
"recommendations": [
{ "itemKey": "CONT0023", "score": 0.95, "position": 1 },
{ "itemKey": "CONT0045", "score": 0.89, "position": 2 }
],
"metadata": {
"modelVersion": "v1.2.0",
"requestId": "req_xyz789",
"inferenceType": "sequential",
"abTestGroup": ""
}
}
}
| Field | Description |
|---|---|
| body.userId | User ID from the request |
| body.recommendations[].itemKey | Recommended item key |
| body.recommendations[].score | Recommendation score (from 0.0 to 1.0) |
| body.recommendations[].position | Recommendation rank |
| body.metadata.modelVersion | Model version used |
| body.metadata.requestId | Request tracking ID. Use this value when sending to the Recommendation Event API |
| body.metadata.inferenceType | Inference type. sequential (history-based), cold_start (attribute-based), popular (popularity-based) |
| body.metadata.abTestGroup | A/B test group (currently returns an empty value) |
Collects user reaction events (such as clicks) on recommendation results. You can analyze the recommendation success rate using the collected event data.
| Method | URI |
|---|---|
| POST | /api/v1.0/recommendation-apps/{appId}/events |
curl example:
curl -X POST "https://{gateway-public-host}/api/v1.0/recommendation-apps/{appId}/events" \
-H "X-NC-APP-KEY: {appKey}" \
-H "X-NHN-Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"eventType": "CLICK",
"requestId": "req_xyz789",
"itemKey": "CONT0023",
"userId": "user_12345",
"context": {
"sessionId": "sess_abc",
"placement": "home_main"
}
}'
Pass the values of requestId, itemKey, and userId exactly as received from the Recommendation API response.
| Field | Required | Description |
|---|---|---|
| eventType | O | Event type. Freely definable (e.g., CLICK, PURCHASE, IMPRESSION). Only letters, numbers, and underscores () are allowed (^[A-Za-z0-9]+$), with a maximum of 64 characters. Stored normalized to uppercase regardless of case. REQUEST and RESPONSE are reserved words and cannot be used |
| requestId | O | The body.metadata.requestId value from the Recommendation API response (opaque string, up to 128 characters) |
| itemKey | O | The itemKey of the recommended item that the user interacted with |
| userId | X | The body.userId value from the Recommendation API response |
| context | X | Additional event information (free-format key-value pairs, e.g., exposure position, placement) |
| userAttributes | X | User attribute information (free-format key-value pairs) |
| options | X | Additional options (free-format key-value pairs) |
A successful response (200) returns only the header.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
}
}
Note