RedCarbon API Documentation

This guide provides comprehensive information about integrating with the RedCarbon security platform.

Overview

The RedCarbon Public API allows you to manage security cases, events, and related entities programmatically. All endpoints use REST principles with JSON payloads.

Base URL

https://api.[env].redcarbon.ai/v1

Authentication

All API requests must include authentication headers. Contact your RedCarbon representative for API credentials.

Authorization: ApiToken YOUR_API_TOKEN
Content-Type: application/json

Common Types and Enums

CaseStatus

Value	Description
UNKNOWN	Unknown status
NEW	Newly created case
UNDER_INVESTIGATION	Case is being investigated
OPEN	Case is open
PENDING	Case is pending action
REPLIED	Case has been replied to
PROCESSING	Case is being processed
CLOSED	Case is closed
ERRORED	Case encountered an error

Severity

Value	Description
NOT_VALID	Undetermined severity
LOW	Low severity
MEDIUM	Medium severity
HIGH	High severity
CRITICAL	Critical severity

IOCType

Value	Description
UNSPECIFIED	Unknown indicator
DOMAIN	Domain indicator
IP_ADDRESS	IP address indicator
EMAIL	Email address indicator
HASH	File hash indicator

Common Data Structures

Case Object

{
  "case_id": "string",
  "customer_id": "string",
  "tier": 0,
  "assigned_to": "string (optional)",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "closed_at": "2024-01-01T00:00:00Z (optional)",
  "status": "NEW",
  "parent_id": "string (optional)",
  "close_notes": "string (optional)",
  "description": "string",
  "title": "string",
  "closed_by": "string (optional)",
  "severity": {
    "value": 0,
    "level": "MEDIUM"
  },
  "security_event_id": "string",
  "first_classification": "string",
  "spent_time_min": 0,
  "tags": ["string"],
  "origin": "string",
  "final_classification": "string (optional)",
  "subscribers": ["string"],
  "mitre": ["string"],
  "category": "string (optional)",
  "security_event": {
    "security_event_id": "string",
    "original_id": "string"
  },
  "annotations": {
    "annotations": {
      "key": {
        "name": "string",
        "url": {
          "url": "string",
          "label": "string"
        }
      }
    }
  }
}

SecurityEvent Object

{
  "id": "string",
  "original_id": "string",
  "customer_id": "string",
  "origin": "string",
  "classification": {
    "type": "string",
    "subtype": "string",
    "vendor": "string"
  },
  "security_event_url": "string (optional)",
  "description": "string",
  "detection_time": "2024-01-01T00:00:00Z",
  "creation_time": "2024-01-01T00:00:00Z",
  "update_time": "2024-01-01T00:00:00Z",
  "ingested_time": "2024-01-01T00:00:00Z",
  "ingested_updated_time": "2024-01-01T00:00:00Z",
  "mitre_tags": ["string"],
  "title": "string",
  "actions": ["string"],
  "detection_engines": ["string"]
}

IOC Object

{
  "indicator": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "type": "DOMAIN"
}

Observable Types

User

{
  "user_name": "string",
  "email": "string (optional)",
  "domain": "string (optional)"
}

Host

{
  "host_name": "string (optional)",
  "host_ips": ["string"]
}

IP

{
  "ip": "string",
  "who_is": {
    "timestamp": "2024-01-01T00:00:00Z",
    "data": "string"
  },
  "location": {
    "timestamp": "2024-01-01T00:00:00Z",
    "data": {
      "latitude": 0.0,
      "longitude": 0.0,
      "precision": 0.0,
      "region": "string",
      "country": "string",
      "city": "string",
      "street_address": "string",
      "postal_code": "string"
    }
  },
  "is_private": true
}

Domain

{
  "domain": "string"
}

File

{
  "filename": "string (optional)",
  "path": "string (optional)",
  "mime_type": "string (optional)",
  "signature": {
    "vendor": "string",
    "verified": true
  }
}

EmailAddress

{
  "email": "string",
  "display_name": "string (optional)"
}

NetworkTraffic

{
  "src_ip": "string",
  "dst_ip": "string",
  "src_port": 0,
  "dst_port": 0,
  "protocols": ["string"],
  "src_byte_count": 0,
  "dst_byte_count": 0,
  "is_active": true,
  "start": "2024-01-01T00:00:00Z",
  "stop": "2024-01-01T00:00:00Z",
  "description": "string",
  "domain": "string"
}

Error Responses

All endpoints may return the following error responses:

HTTP Status	Description
400 Bad Request	INTERNAL
401 Unauthorized	UNAUTHENTICATED
403 Forbidden	PERMISSION_DENIED
404 Not Found	UNIMPLEMENTED
429 Too Many Requests	UNAVAILABLE
502 Bad Gateway	UNAVAILABLE
503 Service Unavailable	UNAVAILABLE
504 Gateway Timeout	UNAVAILABLE
All other codes	UNKNOWN

API Endpoints

Case Management

• Case Operations - Create, update, assign, and close cases
• Case Queries - Retrieve and search cases
• Case Notes & Comments - Add notes and comments to cases

Security Events

• Security Events - Create and retrieve security events

Reports

• Case Reports - Manage case reports and generate HTML reports

IOCs (Indicators of Compromise)

• IOC Management - List and retrieve IOCs

Rate Limiting

API requests are rate-limited to ensure service quality. Current limits:

• 10 requests per second per API token

Pagination

List endpoints support pagination using skip and take parameters:

{
  "skip": 0,
  "take": 50
}

You have to specify the take value, otherwise the responses will include only the total count:

{
  "total": 261
}

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

2024-01-01T12:00:00Z