Resources API

The Resources API allows you to create, manage, and configure resources within your projects. Resources represent deployable services like Graph databases, Flow processors, and AI Assemblers.

Base URL

https://ktrlplane.konnektr.io/api/v1

Authentication

All API requests require authentication using JWT tokens. Include the token in the Authorization header:

Authorization: Bearer <jwt-token>

Resource Object

interface Resource {
  resource_id: string;
  project_id: string;
  name: string;
  type: string;           // "Konnektr.Graph" | "Konnektr.Flow" | "Konnektr.Assembler" | "Konnektr.Compass"
  sku: string;            // "free" | "pro" | "enterprise"
  status: string;         // "creating" | "running" | "updating" | "error" | "terminated"
  settings_json: object;  // Resource-specific configuration
  created_at: string;     // ISO 8601 timestamp
  updated_at: string;     // ISO 8601 timestamp
  error_message?: string; // Present when status is "error"
  access_url?: string;    // Service endpoint URL
}

List Resources

Retrieve all resources in a project.

GET /projects/{projectId}/resources

Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	Project identifier

Example Request

curl -X GET \
  "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources" \
  -H "Authorization: Bearer $JWT_TOKEN"

Example Response

{
  "resources": [
    {
      "resource_id": "res-graph-xyz789",
      "project_id": "proj-abc123",
      "name": "Production Graph DB",
      "type": "Konnektr.Graph",
      "sku": "pro",
      "status": "running",
      "settings_json": {
        "database_name": "production-twins",
        "enable_analytics": true,
        "backup_retention_days": 30
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:35:00Z",
      "access_url": "https://graph-xyz789.konnektr.io/api/v1"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Resource

Create a new resource in a project.

POST /projects/{projectId}/resources

Request Body

interface CreateResourceRequest {
  id: string;                    // Unique resource identifier
  name: string;                  // Display name
  type: string;                  // Resource type
  sku?: string;                  // Billing tier (default: "free")
  settings_json?: object;        // Resource configuration
}

Example Request

curl -X POST \
  "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-graph-db",
    "name": "Customer Analytics Graph",
    "type": "Konnektr.Graph",
    "sku": "pro",
    "settings_json": {
      "database_name": "customer-analytics",
      "enable_analytics": true,
      "backup_retention_days": 30,
      "max_concurrent_connections": 100
    }
  }'

Example Response

{
  "resource_id": "res-graph-abc456",
  "project_id": "proj-abc123",
  "name": "Customer Analytics Graph",
  "type": "Konnektr.Graph",
  "sku": "pro",
  "status": "creating",
  "settings_json": {
    "database_name": "customer-analytics",
    "enable_analytics": true,
    "backup_retention_days": 30,
    "max_concurrent_connections": 100
  },
  "created_at": "2025-01-15T14:20:00Z",
  "updated_at": "2025-01-15T14:20:00Z"
}

Get Resource

Retrieve a specific resource by ID.

GET /projects/{projectId}/resources/{resourceId}

Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	Project identifier
`resourceId`	string	Yes	Resource identifier

Example Request

curl -X GET \
  "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \
  -H "Authorization: Bearer $JWT_TOKEN"

Example Response

{
  "resource_id": "res-graph-xyz789",
  "project_id": "proj-abc123",
  "name": "Production Graph DB",
  "type": "Konnektr.Graph",
  "sku": "pro",
  "status": "running",
  "settings_json": {
    "database_name": "production-twins",
    "enable_analytics": true,
    "backup_retention_days": 30,
    "max_concurrent_connections": 200,
    "enable_audit_logging": true
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T12:45:00Z",
  "access_url": "https://graph-xyz789.konnektr.io/api/v1"
}

Update Resource

Update an existing resource's configuration.

PUT /projects/{projectId}/resources/{resourceId}

Request Body

interface UpdateResourceRequest {
  name?: string;                 // Update display name
  sku?: string;                  // Change billing tier
  settings_json?: object;        // Update configuration
}

Example Request

curl -X PUT \
  "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Graph Database",
    "settings_json": {
      "database_name": "production-twins",
      "enable_analytics": true,
      "backup_retention_days": 60,
      "max_concurrent_connections": 300,
      "enable_audit_logging": true
    }
  }'

Example Response

{
  "resource_id": "res-graph-xyz789",
  "project_id": "proj-abc123",
  "name": "Updated Graph Database",
  "type": "Konnektr.Graph",
  "sku": "pro",
  "status": "updating",
  "settings_json": {
    "database_name": "production-twins",
    "enable_analytics": true,
    "backup_retention_days": 60,
    "max_concurrent_connections": 300,
    "enable_audit_logging": true
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T15:20:00Z"
}

Delete Resource

Delete a resource permanently.

DELETE /projects/{projectId}/resources/{resourceId}

This action is irreversible. All data associated with the resource will be permanently deleted.

Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	Project identifier
`resourceId`	string	Yes	Resource identifier

Example Request

curl -X DELETE \
  "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \
  -H "Authorization: Bearer $JWT_TOKEN"

Example Response

{
  "message": "Resource deletion initiated",
  "resource_id": "res-graph-xyz789",
  "status": "deleting"
}

Resource Configuration Schemas

Resource Configuration

Each resource type accepts a flexible settings_json object. The specific schema depends on the resource type and is validated by the respective Konnektr product.

Example Graph Settings:

{
  "database_name": "my-graph-db",
  "enable_analytics": true,
  "backup_retention_days": 30
}

Example Flow Settings:

{
  "max_concurrent_flows": 10,
  "retention_days": 7,
  "processing_mode": "streaming"
}

Example Assembler Settings:

{
  "model_complexity": "standard",
  "output_format": "dtdl_v2",
  "confidence_threshold": 0.8
}

Settings are stored as flexible JSON and passed to the respective Konnektr product for validation and processing. Refer to each product's documentation for supported configuration options.

Resource Status Codes

Status	Description
`creating`	Resource is being provisioned
`running`	Resource is operational and available
`error`	Resource encountered an error (check error_message)
`deleting`	Resource is being deleted

{
  "error": "Failed to create resource",
  "details": "Invalid resource configuration"
}

403 Forbidden

{
  "error": "Insufficient permissions to create resource"
}

404 Not Found

{
  "error": "Resource not found"
}

SDK Support

KtrlPlane SDKs are planned for future releases. Currently, you can interact with the API directly using HTTP clients in your preferred programming language.

Next Steps

Authentication API: Learn about API authentication
Projects API: Manage projects that contain resources
RBAC API: Control access to resources
Billing API: Monitor resource costs and usage

Resources API

Resources API

Base URL

Authentication

Resource Object

List Resources

Parameters

Example Request

Example Response

Create Resource

Request Body

Example Request

Example Response

Get Resource

Parameters

Example Request

Example Response

Update Resource

Request Body

Example Request

Example Response

Delete Resource

Parameters

Example Request

Example Response

Resource Configuration Schemas

Resource Configuration

Resource Status Codes

Error Handling

Common Error Responses

400 Bad Request

403 Forbidden

404 Not Found

SDK Support

Next Steps