Teams

The Teams API allows you to manage team members, assign roles, and control access to projects and resources within your organization.

Team Object

interface Team {
  id: string;
  name: string;
  description?: string;
  organizationId: string;
  members: TeamMember[];
  permissions: Permission[];
  createdAt: string;
  updatedAt: string;
}

interface TeamMember {
  id: string;
  userId: string;
  teamId: string;
  role: 'owner' | 'admin' | 'member' | 'viewer';
  joinedAt: string;
  user: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
  };
}

List Teams

Retrieve all teams in your organization.

GET /api/teams?page=1&limit=10
Cookie: session-token=your_session_token

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10, max: 100)
search (optional): Search teams by name

{
  "success": true,
  "data": [
    {
      "id": "team_123",
      "name": "AI Engineering Team",
      "description": "Core AI development and monitoring team",
      "organizationId": "org_456",
      "members": [
        {
          "id": "member_789",
          "userId": "user_101",
          "teamId": "team_123",
          "role": "admin",
          "joinedAt": "2024-01-10T10:00:00Z",
          "user": {
            "id": "user_101",
            "name": "Alice Johnson",
            "email": "alice@company.com",
            "avatar": "https://api.cortif.ai/avatars/user_101.jpg"
          }
        }
      ],
      "permissions": [
        {
          "resource": "projects",
          "actions": ["read", "write", "delete"]
        },
        {
          "resource": "alerts",
          "actions": ["read", "write"]
        }
      ],
      "createdAt": "2024-01-10T10:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}

curl -X GET "https://api.cortif.ai/api/teams?page=1&limit=10" \
  -H "Cookie: session-token=your_session_token"

Create Team

Create a new team in your organization.

POST /api/teams
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "name": "Data Science Team",
  "description": "Team focused on model development and validation",
  "permissions": [
    {
      "resource": "projects",
      "actions": ["read", "write"]
    },
    {
      "resource": "runs",
      "actions": ["read", "write"]
    },
    {
      "resource": "evidence-packs",
      "actions": ["read"]
    }
  ]
}

Required Fields:

name: Team name (string, 1-100 characters)

Optional Fields:

description: Team description (string, max 500 characters)
permissions: Initial team permissions

{
  "success": true,
  "data": {
    "id": "team_456",
    "name": "Data Science Team",
    "description": "Team focused on model development and validation",
    "organizationId": "org_456",
    "members": [
      {
        "id": "member_101",
        "userId": "user_123",
        "teamId": "team_456",
        "role": "owner",
        "joinedAt": "2024-01-16T10:00:00Z",
        "user": {
          "id": "user_123",
          "name": "John Doe",
          "email": "john@company.com"
        }
      }
    ],
    "permissions": [
      {
        "resource": "projects",
        "actions": ["read", "write"]
      },
      {
        "resource": "runs",
        "actions": ["read", "write"]
      },
      {
        "resource": "evidence-packs",
        "actions": ["read"]
      }
    ],
    "createdAt": "2024-01-16T10:00:00Z",
    "updatedAt": "2024-01-16T10:00:00Z"
  }
}

curl -X POST https://api.cortif.ai/api/teams \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "name": "Data Science Team",
    "description": "Team focused on model development and validation"
  }'

Get Team

Retrieve a specific team with detailed member information.

GET /api/teams/team_123
Cookie: session-token=your_session_token

{
  "success": true,
  "data": {
    "id": "team_123",
    "name": "AI Engineering Team",
    "description": "Core AI development and monitoring team",
    "organizationId": "org_456",
    "members": [
      {
        "id": "member_789",
        "userId": "user_101",
        "teamId": "team_123",
        "role": "admin",
        "joinedAt": "2024-01-10T10:00:00Z",
        "user": {
          "id": "user_101",
          "name": "Alice Johnson",
          "email": "alice@company.com",
          "avatar": "https://api.cortif.ai/avatars/user_101.jpg"
        }
      },
      {
        "id": "member_790",
        "userId": "user_102",
        "teamId": "team_123",
        "role": "member",
        "joinedAt": "2024-01-12T14:00:00Z",
        "user": {
          "id": "user_102",
          "name": "Bob Smith",
          "email": "bob@company.com"
        }
      }
    ],
    "permissions": [
      {
        "resource": "projects",
        "actions": ["read", "write", "delete"]
      },
      {
        "resource": "alerts",
        "actions": ["read", "write"]
      }
    ],
    "stats": {
      "totalMembers": 8,
      "activeProjects": 12,
      "recentActivity": "2024-01-15T16:30:00Z"
    },
    "createdAt": "2024-01-10T10:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  }
}

curl -X GET https://api.cortif.ai/api/teams/team_123 \
  -H "Cookie: session-token=your_session_token"

Update Team

Update team information and permissions.

PUT /api/teams/team_456
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "name": "Advanced Data Science Team",
  "description": "Team focused on advanced ML model development and validation",
  "permissions": [
    {
      "resource": "projects",
      "actions": ["read", "write", "delete"]
    },
    {
      "resource": "runs",
      "actions": ["read", "write"]
    },
    {
      "resource": "evidence-packs",
      "actions": ["read", "write"]
    },
    {
      "resource": "alerts",
      "actions": ["read"]
    }
  ]
}

{
  "success": true,
  "data": {
    "id": "team_456",
    "name": "Advanced Data Science Team",
    "description": "Team focused on advanced ML model development and validation",
    "organizationId": "org_456",
    "permissions": [
      {
        "resource": "projects",
        "actions": ["read", "write", "delete"]
      },
      {
        "resource": "runs",
        "actions": ["read", "write"]
      },
      {
        "resource": "evidence-packs",
        "actions": ["read", "write"]
      },
      {
        "resource": "alerts",
        "actions": ["read"]
      }
    ],
    "updatedAt": "2024-01-16T11:00:00Z"
  }
}

curl -X PUT https://api.cortif.ai/api/teams/team_456 \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "name": "Advanced Data Science Team",
    "description": "Updated team description"
  }'

Add Team Member

Add a new member to a team with a specific role.

POST /api/teams/team_123/members
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "email": "charlie@company.com",
  "role": "member",
  "sendInvite": true,
  "message": "Welcome to the AI Engineering Team! We're excited to have you on board."
}

Required Fields:

email: User email address

Optional Fields:

role: Member role (default: "member")
sendInvite: Send invitation email (default: true)
message: Custom invitation message

Available Roles:

owner: Full team control and management
admin: Team management and member administration
member: Standard team access
viewer: Read-only access

{
  "success": true,
  "data": {
    "id": "member_791",
    "userId": "user_103",
    "teamId": "team_123",
    "role": "member",
    "status": "invited",
    "joinedAt": null,
    "invitedAt": "2024-01-16T12:00:00Z",
    "user": {
      "id": "user_103",
      "name": "Charlie Brown",
      "email": "charlie@company.com"
    }
  }
}

curl -X POST https://api.cortif.ai/api/teams/team_123/members \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "email": "charlie@company.com",
    "role": "member",
    "sendInvite": true
  }'

Update Member Role

Change a team member's role or permissions.

PATCH /api/teams/team_123/members/member_790
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "role": "admin",
  "reason": "Promoted to team lead position"
}

{
  "success": true,
  "data": {
    "id": "member_790",
    "userId": "user_102",
    "teamId": "team_123",
    "role": "admin",
    "joinedAt": "2024-01-12T14:00:00Z",
    "updatedAt": "2024-01-16T12:30:00Z",
    "user": {
      "id": "user_102",
      "name": "Bob Smith",
      "email": "bob@company.com"
    }
  }
}

curl -X PATCH https://api.cortif.ai/api/teams/team_123/members/member_790 \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "role": "admin"
  }'

Remove Team Member

Remove a member from a team.

DELETE /api/teams/team_123/members/member_791
Cookie: session-token=your_session_token

{
  "success": true,
  "message": "Member removed from team successfully"
}

curl -X DELETE https://api.cortif.ai/api/teams/team_123/members/member_791 \
  -H "Cookie: session-token=your_session_token"

Test Webhook

Test team notification webhooks for alerts and updates.

POST /api/teams/test-webhook
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "Test notification from Cortif.AI",
  "teamId": "team_123"
}

{
  "success": true,
  "data": {
    "status": "delivered",
    "responseCode": 200,
    "responseTime": 245,
    "timestamp": "2024-01-16T13:00:00Z"
  }
}

curl -X POST https://api.cortif.ai/api/teams/test-webhook \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "webhookUrl": "https://hooks.slack.com/services/...",
    "message": "Test notification"
  }'

Team Analytics

Get team activity and performance analytics.

GET /api/teams/team_123/analytics?period=30d
Cookie: session-token=your_session_token

Query Parameters:

period: Time period (7d, 30d, 90d)
metrics: Specific metrics to include

{
  "success": true,
  "data": {
    "teamId": "team_123",
    "period": "30d",
    "activity": {
      "totalActions": 1250,
      "projectsCreated": 8,
      "runsExecuted": 145,
      "alertsHandled": 23,
      "evidencePacksGenerated": 12
    },
    "members": {
      "total": 8,
      "active": 7,
      "newJoins": 2,
      "departures": 0
    },
    "performance": {
      "avgResponseTime": "2h 15m",
      "alertResolutionRate": 0.91,
      "projectSuccessRate": 0.96
    },
    "topContributors": [
      {
        "userId": "user_101",
        "name": "Alice Johnson",
        "actions": 245,
        "projectsLed": 3
      }
    ]
  }
}

Role-Based Permissions

Permission Matrix

Resource	Owner	Admin	Member	Viewer
Projects	CRUD	CRUD	CRU	R
Runs	CRUD	CRUD	CRU	R
Alerts	CRUD	CRUD	RU	R
Evidence Packs	CRUD	CRUD	CR	R
Team Management	CRUD	CRU	-	-
Organization Settings	CRUD	R	-	-

Legend:

C: Create
R: Read
U: Update
D: Delete

Custom Permissions

Define granular permissions for specific resources:

{
  "permissions": [
    {
      "resource": "projects",
      "actions": ["read", "write"],
      "conditions": {
        "projectType": ["ml", "nlp"],
        "environment": ["staging", "development"]
      }
    },
    {
      "resource": "alerts",
      "actions": ["read", "acknowledge"],
      "conditions": {
        "severity": ["medium", "high", "critical"]
      }
    }
  ]
}

Error Handling

Common error responses for team operations:

Status Code	Error	Description
`400`	`INVALID_INPUT`	Invalid request data
`401`	`UNAUTHORIZED`	Authentication required
`403`	`FORBIDDEN`	Insufficient permissions
`404`	`TEAM_NOT_FOUND`	Team doesn't exist
`409`	`MEMBER_EXISTS`	User is already a team member
`422`	`VALIDATION_ERROR`	Input validation failed

SDK Examples

JavaScript/TypeScript

import { CortifClient } from '@cortif/sdk';

const client = new CortifClient();

// Create team
const team = await client.teams.create({
  name: 'ML Operations Team',
  description: 'Team responsible for ML model operations',
  permissions: [
    {
      resource: 'projects',
      actions: ['read', 'write']
    }
  ]
});

// Add team member
await client.teams.addMember(team.id, {
  email: 'newmember@company.com',
  role: 'member',
  sendInvite: true
});

// Update member role
await client.teams.updateMember(team.id, 'member_123', {
  role: 'admin'
});

// Get team analytics
const analytics = await client.teams.getAnalytics(team.id, {
  period: '30d'
});

Python

from cortif import CortifClient

client = CortifClient()

# Create team
team = client.teams.create({
    'name': 'ML Operations Team',
    'description': 'Team responsible for ML model operations',
    'permissions': [
        {
            'resource': 'projects',
            'actions': ['read', 'write']
        }
    ]
})

# Add team member
client.teams.add_member(team['id'], {
    'email': 'newmember@company.com',
    'role': 'member',
    'send_invite': True
})

# Update member role
client.teams.update_member(team['id'], 'member_123', {
    'role': 'admin'
})

# Get team analytics
analytics = client.teams.get_analytics(team['id'], period='30d')

Best Practices

Team Management Tips

Clear Roles: Define clear roles and responsibilities for each team member
Least Privilege: Grant minimum necessary permissions for each role
Regular Reviews: Periodically review team membership and permissions
Onboarding: Provide proper onboarding for new team members
Documentation: Document team processes and procedures
Communication: Set up proper notification channels for team updates

Integration Examples

Slack Integration

Configure Slack notifications for team activities:

{
  "integrations": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/...",
      "channel": "#ai-team",
      "notifications": [
        "member_joined",
        "member_left",
        "role_changed",
        "project_created",
        "alert_triggered"
      ]
    }
  }
}

Microsoft Teams Integration

Set up Microsoft Teams notifications:

{
  "integrations": {
    "msteams": {
      "webhookUrl": "https://outlook.office.com/webhook/...",
      "notifications": [
        "daily_summary",
        "critical_alerts",
        "project_updates"
      ]
    }
  }
}

Team Templates

Create reusable team templates for common organizational structures:

{
  "templates": [
    {
      "name": "Data Science Team Template",
      "description": "Standard template for data science teams",
      "defaultPermissions": [
        {
          "resource": "projects",
          "actions": ["read", "write"]
        },
        {
          "resource": "runs",
          "actions": ["read", "write"]
        }
      ],
      "defaultRoles": [
        {
          "name": "Team Lead",
          "role": "admin",
          "count": 1
        },
        {
          "name": "Data Scientists",
          "role": "member",
          "count": 5
        }
      ]
    }
  ]
}

Teams

Teams

Team Object

List Teams

Create Team

Get Team

Update Team

Add Team Member

Update Member Role

Remove Team Member

Test Webhook

Team Analytics

Role-Based Permissions

Permission Matrix

Custom Permissions

Error Handling

SDK Examples

JavaScript/TypeScript

Python

Best Practices

Integration Examples

Slack Integration

Microsoft Teams Integration

Team Templates

Next Steps

On this page