Skip to main content
Categories are the top-level classification system in G2C Platform’s hierarchical structure.
Categories serve as the primary organizational unit for digital objects. Your company is automatically determined from your API key.

​
Endpoint

curl -X POST "https://api.g2cplatform.com/v2/categories" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electronics",
    "description": "Electronic devices and components",
    "metadata": {
      "department": "IT",
      "priority": "high"
    }
  }'

​
Request

​
HTTP Method

POST

​
URL

https://api.g2cplatform.com/v2/categories

​
Path Parameters

None. Your company is automatically identified from your API key.

​
Request Body

FieldTypeRequiredDescription
namestring✅Category name (2-100 characters)
descriptionstring❌Category description (max 500 characters)
metadataobject❌Additional metadata as key-value pairs

​
Headers

X-API-Key: YOUR_API_KEY
Content-Type: application/json

​
Response

​
Success Response (201 Created)

{
  "id": "cat_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
  "name": "Electronics",
  "description": "Electronic devices and components",
  "status": "active",
  "metadata": {
    "department": "IT",
    "priority": "high"
  },
  "createdAt": "2025-08-03T10:30:00Z",
  "updatedAt": "2025-08-03T10:30:00Z",
  "statistics": {
    "subcategoryCount": 0,
    "objectCount": 0
  }
}

​
Response Headers

The response includes a Location header with the URL of the created category: 
Location: https://api.g2cplatform.com/v2/categories/cat_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o

​
Error Responses

​
400 Bad Request

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-08-03T10:30:00Z",
  "validationErrors": [
    {
      "field": "name",
      "message": "Name must be between 2 and 100 characters",
      "code": "LENGTH_INVALID"
    }
  ]
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-08-03T10:30:00Z"
}

​
403 Forbidden

{
  "error": "Access denied to company",
  "code": "COMPANY_ACCESS_DENIED",
  "timestamp": "2025-08-03T10:30:00Z"
}

​
409 Conflict

{
  "error": "Category name already exists",
  "code": "CATEGORY_NAME_EXISTS",
  "timestamp": "2025-08-03T10:30:00Z"
}

​
Implementation Examples

​
Basic Category Creation

async function createCategory(companyId, categoryData) {
  try {
    const response = await fetch(
      `https://api.g2cplatform.com/v2/categories`,
      {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(categoryData)
      }
    );

    if (response.ok) {
      const category = await response.json();
      console.log('✅ Category created successfully:', category.id);
      return category;
    } else {
      const error = await response.json();
      throw new Error(`Category creation failed: ${error.error}`);
    }
  } catch (error) {
    console.error('❌ Category creation error:', error.message);
    throw error;
  }
}

// Usage
const category = await createCategory('company-uuid', {
  name: 'Office Supplies',
  description: 'General office supplies and equipment',
  metadata: {
    location: 'Building A',
    manager: 'John Smith'
  }
});

​
Category with Validation

function validateCategoryData(data) {
  const errors = [];

  if (!data.name || data.name.length < 2 || data.name.length > 100) {
    errors.push('Name must be between 2 and 100 characters');
  }

  if (data.description && data.description.length > 500) {
    errors.push('Description must not exceed 500 characters');
  }

  if (errors.length > 0) {
    throw new Error(`Validation failed: ${errors.join(', ')}`);
  }
}

async function createValidatedCategory(companyId, categoryData) {
  // Validate data before sending
  validateCategoryData(categoryData);

  const response = await fetch(
    `https://api.g2cplatform.com/v2/categories`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.G2C_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(categoryData)
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error}`);
  }

  return response.json();
}

​
Bulk Category Creation

async function createMultipleCategories(companyId, categoriesData) {
  const results = [];

  for (const categoryData of categoriesData) {
    try {
      const category = await createCategory(companyId, categoryData);
      results.push({ success: true, category });
    } catch (error) {
      results.push({
        success: false,
        error: error.message,
        data: categoryData
      });
    }
  }

  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);

  console.log(`✅ Created ${successful.length} categories`);
  if (failed.length > 0) {
    console.log(`❌ Failed to create ${failed.length} categories`);
  }

  return { successful, failed };
}

// Usage
const categoriesData = [
  { name: 'IT Equipment', description: 'Computers and technology' },
  { name: 'Furniture', description: 'Office furniture and fixtures' },
  { name: 'Vehicles', description: 'Company vehicles and transport' }
];

const results = await createMultipleCategories('company-uuid', categoriesData);

​
Best Practices

  • Use clear, descriptive names for categories
  • Keep names concise but meaningful
  • Consider future expansion when naming
  • Use consistent naming patterns across categories
  • Use metadata for additional categorization
  • Store department, location, or manager information
  • Add cost center or budget codes
  • Include custom fields specific to your organization
  • Always check response status codes
  • Handle validation errors gracefully
  • Implement retry logic for network failures
  • Log errors for debugging and monitoring
  • Create categories in batches when possible
  • Cache category data to reduce API calls
  • Use metadata to avoid creating too many categories
  • Plan your category hierarchy before implementation

​
Next Steps

List Categories

Retrieve and filter your categories

Create Subcategory

Add subcategories to organize objects further

Update Category

Modify category information and metadata

Create Object

Start adding digital objects to your category