Get All Groups

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/groups \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "groups": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c25",
      "name": "Engineering Team",
      "description": "Software engineering team",
      "status": "Active",
      "userCount": 15,
      "users": [
        {
          "id": "60a7c8f5e8b4f5001f7a8c24",
          "name": "John Doe",
          "email": "john@example.com"
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

GET

groups

Get All Groups

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/groups \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "groups": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c25",
      "name": "Engineering Team",
      "description": "Software engineering team",
      "status": "Active",
      "userCount": 15,
      "users": [
        {
          "id": "60a7c8f5e8b4f5001f7a8c24",
          "name": "John Doe",
          "email": "john@example.com"
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

List Groups

Retrieve a list of all user groups in the system with pagination and filtering options.

Endpoint

GET /groups

Description

This endpoint returns all user groups available in the SecureAI system. It provides detailed information about each group including members, permissions, and metadata. This is useful for managing user access and organizational structure.

Authentication

Required: API Key with admin privileges

Authorization: Bearer sk-your-api-key-here

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	1	Page number for pagination
`limit`	integer	No	20	Number of groups per page (1-100)
`search`	string	No	-	Search term for group name or description
`status`	string	No	-	Filter by group status
`sortBy`	string	No	createdAt	Field to sort by
`sortOrder`	string	No	desc	Sort order (asc, desc)

Example Request

GET /groups?search=engineering&limit=20&page=1&sortBy=createdAt&sortOrder=desc

Success Response

Status Code: 200 OK

{
  "success": true,
  "groups": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c25",
      "name": "Engineering Team",
      "description": "Software engineering and development team",
      "status": "Active",
      "userCount": 15,
      "users": [
        {
          "id": "60a7c8f5e8b4f5001f7a8c24",
          "name": "John Doe",
          "email": "john@example.com"
        }
      ],
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "pages": 2
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`groups[]`	array	Array of group objects
`groups[].id`	string	Unique group identifier
`groups[].name`	string	Group name
`groups[].description`	string	Group description
`groups[].status`	string	Group status
`groups[].userCount`	integer	Number of users in the group
`groups[].users`	array	Array of user objects in the group
`groups[].users[].id`	string	User ID
`groups[].users[].name`	string	User name
`groups[].users[].email`	string	User email
`groups[].createdAt`	string	Creation timestamp
`pagination`	object	Pagination information

Example Usage

JavaScript

const listGroups = async (params = {}) => {
  const queryString = new URLSearchParams(params).toString();
  const url = `https://{customer.name}.hiperai.ai/api/external/groups${queryString ? `?${queryString}` : ''}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here'
    }
  });
  
  return await response.json();
};

// Example usage
const result = await listGroups({
  search: 'engineering',
  limit: 10,
  page: 1,
  sortBy: 'createdAt',
  sortOrder: 'desc'
});
console.log(result.groups);

Python

import requests

def list_groups(params=None):
    url = "https://{customer.name}.hiperai.ai/api/external/groups"
    headers = {
        "Authorization": "Bearer sk-your-api-key-here"
    }
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Example usage
params = {
    "search": "engineering",
    "limit": 10,
    "page": 1,
    "sortBy": "createdAt",
    "sortOrder": "desc"
}

result = list_groups(params)
print(result["groups"])

cURL

curl -X GET "https://{customer.name}.hiperai.ai/api/external/groups?search=engineering&limit=10&page=1&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer sk-your-api-key-here"

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin privileges required"
  }
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 60
  }
}

Filtering Examples

Search Groups

# Search by name
GET /groups?search=engineering

# Search by description
GET /groups?search=development

Sort Options

# Sort by name ascending
GET /groups?sortBy=name&sortOrder=asc

# Sort by user count descending
GET /groups?sortBy=userCount&sortOrder=desc

# Sort by creation date
GET /groups?sortBy=createdAt&sortOrder=desc

Pagination

# Get first 20 groups
GET /groups?limit=20&page=1

# Get next 20 groups
GET /groups?limit=20&page=2

Use Cases

Group Management: List all groups for administrative purposes
User Organization: Discover available groups for user assignment
Access Control: Review group permissions and member counts
Reporting: Generate reports on group structure and membership
Integration: Discover groups for application integration

Rate Limits

Default: 100 requests per minute
Daily: 10,000 requests per day
Monthly: 300,000 requests per month

Notes

This endpoint is only accessible by administrators
Pagination: Uses page parameter, not offset
Flat Response: Response is not nested under data object
User Details: Includes full user information for each group member
Status Filter: Can filter by group status
Search functionality works across group names and descriptions
Sorting options help organize results by different criteria

Authorizations

Authorization

string

header

required

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

Query Parameters

page

integer

default:1

Page number for pagination

Required range: x >= 1

limit

integer

default:20

Number of groups per page

Required range: 1 <= x <= 100

string

Search term for group name or description

status

enum<string>

Filter by group status

Available options:

Active,

Inactive

sortBy

string

default:createdAt

Field to sort by

sortOrder

enum<string>

default:desc

Sort order

Available options:

asc,

desc

Response

List of groups

success

boolean

Example:

true

groups

object[]

Show child attributes

pagination

object

Show child attributes

Primeros Pasos & Setup

Modelos & Generación AI

Knowledge Base & RAG

Seguridad, Guardrails & Auditoría

Usuarios & Acceso (IAM)

Facturación, Cuotas & Webhooks

List Groups

List Groups

Endpoint

Description

Authentication

Query Parameters

Example Request

Success Response

Response Fields

Example Usage

JavaScript

Python

cURL

Error Responses

401 Unauthorized

403 Forbidden

429 Too Many Requests

Filtering Examples

Search Groups

Sort Options

Use Cases

Rate Limits

Notes

Authorizations

Query Parameters

Response

​List Groups

​Endpoint

​Description

​Authentication

​Query Parameters

​Example Request

​Success Response

​Response Fields

​Example Usage

​JavaScript

​Python

​cURL

​Error Responses

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​Filtering Examples

​Search Groups

​Sort Options

​Pagination

​Use Cases

​Rate Limits

​Notes

Authorizations

Query Parameters

Response

List Groups

Endpoint

Description

Authentication

Query Parameters

Example Request

Success Response

Response Fields

Example Usage

JavaScript

Python

cURL

Error Responses

401 Unauthorized

403 Forbidden

429 Too Many Requests

Filtering Examples

Search Groups

Sort Options

Pagination

Use Cases

Rate Limits

Notes