Skip to main content
Subcategories are included in the response.

​
Prerequisites

  • Valid API key with category read permissions

​
Request

curl -X GET "https://api.g2cplatform.com/v2/categories?limit=20&offset=0&status=active" \
  -H "X-API-Key: your-api-key"

​
Query Parameters

ParameterTypeRequiredDescription
limitnumberNoMaximum number of categories to return (default: 20, max: 100)
offsetnumberNoNumber of categories to skip for pagination (default: 0)
statusstringNoFilter by status: “active”, “inactive”, “all” (default: “active”)
namestringNoFilter by category name (partial match)
sortstringNoSort order: “createdAt:desc”, “createdAt:asc”, “name:asc”, “name:desc” (default: “createdAt:desc”)

​
Response

{
  "data": [
    {
      "id": "cat_abc123...",
      "name": "Electronics",
      "description": "Electronic devices and components",
      "status": "active",
      "metadata": {
        "department": "Technology"
      },
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z",
      "statistics": {
        "subcategoryCount": 5,
        "objectCount": 150
      },
      "subcategories": [
        {
          "id": "sub_def456...",
          "name": "Smartphones",
          "description": "Mobile phones and accessories",
          "status": "active",
          "categoryId": "cat_abc123...",
          "createdAt": "2025-01-15T11:00:00Z",
          "updatedAt": "2025-01-15T11:00:00Z",
          "statistics": {
            "objectCount": 45
          }
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "hasNext": true,
    "hasPrevious": false
  }
}

​
Response Fields

FieldTypeDescription
dataarrayArray of category objects
paginationobjectPagination information

​
Category Object

FieldTypeDescription
idstringUnique category identifier
namestringCategory name
descriptionstringCategory description
statusstringCategory status
metadataobjectAdditional metadata
createdAtstringISO 8601 timestamp of creation
updatedAtstringISO 8601 timestamp of last update
statisticsobjectCategory statistics
subcategoriesarrayArray of subcategory objects

​
Pagination Object

FieldTypeDescription
limitnumberCurrent page size
offsetnumberCurrent offset
totalnumberTotal number of categories matching criteria
hasNextbooleanWhether more items are available
hasPreviousbooleanWhether previous items exist

​
Examples

​
List All Categories

GET /categories?limit=50&offset=0

​
List Active Categories Only

GET /categories?status=active&limit=20&offset=0

​
Search Categories by Name

GET /categories?name=electronic&limit=10&offset=0

​
Sort Categories by Name

GET /categories?sort=name:asc&limit=25&offset=0

​
Error Responses

Status CodeDescription
400Invalid query parameters
401Unauthorized - invalid API key
403Insufficient permissions
500Internal server error

​
Pagination Best Practices

  • Use limit to control page size (recommended: 20-50 items)
  • Use offset to navigate through pages
  • Check hasNext before requesting the next page
  • Consider filtering for better performance on large datasets