API Endpoints Guide

api
documentation
development
Comprehensive documentation of our API endpoints, parameters, and response formats
Published

January 20, 2025

API Endpoints Guide

Comprehensive documentation for authentication, requests, and response formats.

API Overview

The chen.ist API is a RESTful service that allows developers to access and integrate our services into their applications. The API provides endpoints for security assessment, cloud resource management, and data analysis.

Base URL

https://api.chen.ist/v1

Response Format

All responses are returned in JSON format with status and data fields.

Pagination

Collection endpoints support page and limit parameters (default: 20, max: 100).

Response Examples

Standard response envelope used by all endpoints.

Success Response

{
  "status": "success",
  "data": {
    "property1": "value1",
    "property2": "value2"
  }
}

Error Response

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameter: id",
    "details": "The id parameter must be a valid UUID"
  }
}

Paginated Response

{
  "status": "success",
  "data": [],
  "pagination": {
    "total_items": 243,
    "total_pages": 13,
    "current_page": 2,
    "items_per_page": 20,
    "next_page": "/v1/resources?page=3&limit=20",
    "prev_page": "/v1/resources?page=1&limit=20"
  }
}

Authentication

API Keys

Authentication is performed using API keys. Include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

Obtaining an API Key

  1. Log in to your chen.ist account
  2. Navigate to the Developer Dashboard
  3. Select “API Keys”
  4. Click “Generate New Key”
  5. Name your key and select the appropriate permissions
  6. Store your key securely - it will only be displayed once

Rate Limiting

API requests are rate-limited to ensure fair usage. The following headers are included in each response:

  • X-Rate-Limit-Limit: The maximum number of requests allowed per hour
  • X-Rate-Limit-Remaining: The number of requests remaining in the current window
  • X-Rate-Limit-Reset: The time at which the current rate limit window resets (Unix timestamp)

Security Assessment API

Get Security Assessment

Endpoint: GET /security/assessments/{id}

Parameters:

  • id (path, required): The assessment ID

Response:

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "resource_id": "server-12345",
    "resource_type": "virtual_machine",
    "timestamp": "2025-01-15T14:30:00Z",
    "score": 85,
    "findings": [
      {
        "id": "finding-123",
        "severity": "high",
        "category": "authentication",
        "description": "Weak password policy detected",
        "remediation": "Implement stronger password requirements"
      },
      {
        "id": "finding-124",
        "severity": "medium",
        "category": "network",
        "description": "Unnecessary open ports detected",
        "remediation": "Close unused network ports"
      }
    ],
    "summary": {
      "high_severity": 1,
      "medium_severity": 3,
      "low_severity": 2,
      "passing_checks": 45
    }
  }
}

Create Security Assessment

Endpoint: POST /security/assessments

Request Body:

{
  "resource_id": "server-12345",
  "resource_type": "virtual_machine",
  "scan_options": {
    "comprehensive": true,
    "categories": ["authentication", "network", "encryption"]
  }
}

Response:

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "resource_id": "server-12345",
    "resource_type": "virtual_machine",
    "status": "pending",
    "estimated_completion_time": "2025-01-15T14:35:00Z"
  }
}

List Security Assessments

Endpoint: GET /security/assessments

Parameters:

  • resource_id (query, optional): Filter by resource ID
  • resource_type (query, optional): Filter by resource type
  • from_date (query, optional): Filter by start date (ISO 8601 format)
  • to_date (query, optional): Filter by end date (ISO 8601 format)
  • page (query, optional): Page number
  • limit (query, optional): Items per page

Response:

{
  "status": "success",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
      "resource_id": "server-12345",
      "resource_type": "virtual_machine",
      "timestamp": "2025-01-15T14:30:00Z",
      "score": 85
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-2345678901ab",
      "resource_id": "server-67890",
      "resource_type": "virtual_machine",
      "timestamp": "2025-01-14T10:15:00Z",
      "score": 92
    }
  ],
  "pagination": {
    "total_items": 15,
    "total_pages": 1,
    "current_page": 1,
    "items_per_page": 20
  }
}

Cloud Resources API

List Resources

Endpoint: GET /cloud/resources

Parameters:

  • type (query, optional): Filter by resource type
  • provider (query, optional): Filter by cloud provider
  • region (query, optional): Filter by region
  • tag (query, optional): Filter by tag (can be specified multiple times)
  • page (query, optional): Page number
  • limit (query, optional): Items per page

Response:

{
  "status": "success",
  "data": [
    {
      "id": "vm-12345",
      "name": "web-server-01",
      "type": "virtual_machine",
      "provider": "aws",
      "region": "us-east-1",
      "status": "running",
      "created_at": "2024-10-15T08:30:00Z",
      "tags": [
        {"key": "environment", "value": "production"},
        {"key": "application", "value": "web"}
      ]
    }
  ],
  "pagination": {
    "total_items": 45,
    "total_pages": 3,
    "current_page": 1,
    "items_per_page": 20
  }
}

Get Resource

Endpoint: GET /cloud/resources/{id}

Parameters:

  • id (path, required): The resource ID

Response:

{
  "status": "success",
  "data": {
    "id": "vm-12345",
    "name": "web-server-01",
    "type": "virtual_machine",
    "provider": "aws",
    "region": "us-east-1",
    "status": "running",
    "created_at": "2024-10-15T08:30:00Z",
    "updated_at": "2025-01-10T14:20:00Z",
    "tags": [
      {"key": "environment", "value": "production"},
      {"key": "application", "value": "web"}
    ],
    "details": {
      "instance_type": "t3.large",
      "vpc_id": "vpc-12345",
      "subnet_id": "subnet-67890",
      "public_ip": "203.0.113.10",
      "private_ip": "10.0.1.10",
      "security_groups": [
        {"id": "sg-12345", "name": "web-servers"}
      ],
      "volumes": [
        {"id": "vol-12345", "size_gb": 100, "type": "gp3"}
      ]
    }
  }
}

Update Resource Tags

Endpoint: PATCH /cloud/resources/{id}/tags

Parameters:

  • id (path, required): The resource ID

Request Body:

{
  "tags": [
    {"key": "environment", "value": "staging"},
    {"key": "application", "value": "web"},
    {"key": "owner", "value": "platform-team"}
  ]
}

Data Analysis API

Create Analysis Job

Endpoint: POST /data/analysis/jobs

Request Body:

{
  "name": "Monthly Security Analysis",
  "description": "Analysis of security events for January 2025",
  "data_source": {
    "type": "security_logs",
    "parameters": {
      "start_date": "2025-01-01T00:00:00Z",
      "end_date": "2025-01-31T23:59:59Z",
      "log_types": ["firewall", "authentication", "system"]
    }
  },
  "analysis_type": "security_event_correlation",
  "output_format": "json",
  "notification": {
    "email": "user@example.com",
    "webhook_url": "https://example.com/webhook"
  }
}

Get Analysis Job

Endpoint: GET /data/analysis/jobs/{id}

Parameters:

  • id (path, required): The job ID

List Analysis Jobs

Endpoint: GET /data/analysis/jobs

Parameters:

  • status (query, optional): Filter by job status
  • created_after (query, optional): Filter by creation date
  • type (query, optional): Filter by analysis type
  • page (query, optional): Page number
  • limit (query, optional): Items per page

Error Codes

Code Description
authentication_error Invalid or missing API key
authorization_error Insufficient permissions for the requested operation
invalid_request Invalid request parameters
resource_not_found The requested resource does not exist
rate_limit_exceeded Rate limit has been exceeded
internal_error An internal server error occurred
service_unavailable The service is temporarily unavailable

Code Examples

Python Example

import requests
import json

API_KEY = "your_api_key"
BASE_URL = "https://api.chen.ist/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Get a list of security assessments
response = requests.get(
    f"{BASE_URL}/security/assessments",
    headers=headers,
    params={
        "resource_type": "virtual_machine",
        "from_date": "2025-01-01T00:00:00Z",
        "limit": 10
    }
)

if response.status_code == 200:
    assessments = response.json()["data"]
    print(f"Found {len(assessments)} assessments")
    for assessment in assessments:
        print(f"ID: {assessment['id']}, Score: {assessment['score']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

JavaScript Example

const API_KEY = "your_api_key";
const BASE_URL = "https://api.chen.ist/v1";

// Create a security assessment
async function createSecurityAssessment() {
    try {
        const response = await fetch(`${BASE_URL}/security/assessments`, {
            method: "POST",
            headers: {
                "Authorization": `Bearer ${API_KEY}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify({
                "resource_id": "server-12345",
                "resource_type": "virtual_machine",
                "scan_options": {
                    "comprehensive": true,
                    "categories": ["authentication", "network", "encryption"]
                }
            })
        });

        const data = await response.json();

        if (response.ok) {
            console.log("Assessment created:", data.data.id);
            return data.data.id;
        } else {
            console.error("Error creating assessment:", data.error);
            return null;
        }
    } catch (error) {
        console.error("API request failed:", error);
        return null;
    }
}

createSecurityAssessment();

cURL Example

# List cloud resources
curl -X GET "https://api.chen.ist/v1/cloud/resources?type=virtual_machine&provider=aws" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

# Create a data analysis job
curl -X POST "https://api.chen.ist/v1/data/analysis/jobs" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Security Analysis",
    "data_source": {
      "type": "security_logs",
      "parameters": {
        "start_date": "2025-01-01T00:00:00Z",
        "end_date": "2025-01-31T23:59:59Z",
        "log_types": ["firewall", "authentication", "system"]
      }
    },
    "analysis_type": "security_event_correlation",
    "output_format": "json"
  }'

Need API support?

Our developer team is ready to help you integrate.

Contact API Support
Developer docs   Code examples   Dedicated support
Back to top