Using the PointFive API | PointFive Help Center

The PointFive platform provides a comprehensive GraphQL API for managing teams and users in your organization. These APIs enable you to programmatically create organizational structures, manage team memberships, control resource access, and handle user lifecycle operations.

All available updates (Mutations), including those outlined here, can be fully explored in the API Playground. Note that you need to be logged in to be able to access it.

This tool allows you to browse the schema, test queries, and see all supported operations directly from your browser.

Opportunities API

List Opportunities

Retrieve opportunities with filtering, sorting, and pagination.

query ListOpportunities {
  opportunities(
    where: {
      status: { IN: [OPEN, IN_PROGRESS] }
      savingAmount: { GTE: 100 }
      definitionCategory: { IN: [unused_resource, underutilization] }
    }
    limit: 20
    offset: 0
    orderBy: [{ savingAmount: DESC }]
  ) {
    id
    name
    savingAmount
    currentCost
    priority
    risk
    effort
    status
    resource {
      name
      provider
      service
      region
    }
  }
}

Common Filters:

status - Filter by OPEN, IN_PROGRESS, VALIDATED, RESOLVED, or DISMISSED
savingAmount - Filter by potential savings (supports GTE, LTE, GT, LT, EQ)
definitionCategory - Filter by opportunity type
risk - Filter by risk level (1-5)
effort - Filter by implementation effort (1-5)
assignedUser - Filter by assigned user
projectId - Filter by specific project
Use Cases:

Find high-value opportunities above a savings threshold
List opportunities for specific cloud services
Get opportunities assigned to your team
Filter by risk/effort for prioritization

Get Single Opportunity

Retrieve detailed information about a specific opportunity.

Required Role: ADMIN or MEMBER

query GetOpportunity {
  opportunity(id: "opportunity-uuid") {
    id
    name
    diagnosis {
      description
      descriptionText
      data
    }
    recommendation {
      summary
      summaryText
    }
    savingAmount
    currentCost
    priority
    risk
    effort
    status
    resource {
      id
      name
      provider
      service
      region
      tags
    }
    remediationLinks {
      name
      url
    }
    platformUrl
  }
}

Export Opportunities

Generate a downloadable export of opportunities data.

query ExportOpportunities {
  opportunitiesExport(
    where: { status: { IN: [OPEN] } }
    exportType: CSV
  )
}

Export Formats:

CSV - Comma-separated values
JSON - JSON format

Response: Returns a presigned URL for downloading the export file.

Resources API

Export Resources

Generate a downloadable export of your cloud resources.

Required Role: ADMIN or MEMBER

query ExportResources {
  resourcesExport(
    where: {
      provider: { IN: [AWS, GCP, AZURE] }
      service: { IN: ["EC2", "S3", "RDS"] }
      region: { IN: ["us-east-1", "us-west-2"] }
      tags: { 
        hasKeyValue: [
          { key: "Environment", value: "production" }
        ] 
      }
    }
    exportType: CSV
    orderBy: [{ cost: DESC }]
  )
}

Common Filters:

provider - Filter by AWS, GCP, or AZURE
service - Filter by cloud service (EC2, S3, RDS, etc.)
region - Filter by cloud region
resourceType - Filter by resource type
tags - Filter by resource tags
cost - Filter by resource cost

Use Cases:

Export resource inventory for analysis
Generate reports for specific regions or services
Audit resources by tags or cost thresholds

Teams API

Teams organize users into groups for access control and resource management. Teams can have hierarchical structures and resource allocation rules.

Get Team

Retrieve detailed information about a specific team.

Required Role: ADMIN

query GetTeam {
  getTeam(id: "team-uuid-here") {
    id
    name
    type
    members {
      userId
      user {
        firstName
        lastName
        email
      }
    }
    memberCount
    childTeams {
      id
      name
    }
    parentTeams {
      id
      name
    }
    resourceAllocationRules {
      name
      rule
    }
    createdAt
    updatedAt
  }
}

Parameters:

id (UUID) - Team ID
name (String) - Team name (provide either id or name)

List Teams

Retrieve all teams with optional filtering.

Required Role: ADMIN or MEMBER

query ListTeams {
  listTeams(
    where: { name: { contains: "Engineering" }, type: TEAM, orphan: false }
    limit: 50
    offset: 0
  ) {
    id
    name
    type
    memberCount
    resourceAllocationRulesCount
    createdAt
  }
}

Filters:

name - Filter by team name (supports contains, equals, etc.)
type - Filter by ORGANIZATION or TEAM
orphan - If true, only return teams with no parent

Create Team

Create a new team.

Required Role: ADMIN

mutation CreateTeam {
  createTeam(input: { name: "Platform Engineering", members: ["user-uuid-1", "user-uuid-2"] }) {
    id
    name
    type
    members {
      userId
      user {
        firstName
        lastName
      }
    }
    createdAt
  }
}

Input:

name (required) - Team name (1-80 characters, must be unique)
members (optional) - List of user IDs to add as initial members

Update Team

Update an existing team's information.

Required Role: ADMIN

graphql

mutation UpdateTeam {
  updateTeam(
    id: "team-uuid-here"
    input: {
      name: "Updated Team Name"
      ResourceAllocationRules: [
        {
          name: "Production Resources"
          rule: { AND: [{ tag: { IN: { Key: "Environment", Values: ["production"] } } }] }
        }
      ]
    }
  ) {
    success
    team {
      id
      name
      resourceAllocationRules {
        name
        rule
      }
    }
  }
}

Add Members to Team

Add users to a team.

Required Role: ADMIN

mutation AddMembers {
  addMembersToTeam(id: "team-uuid-here", userIds: ["user-uuid-1", "user-uuid-2"]) {
    success
  }
}

Remove Member from Teams

Remove a user from multiple teams.

Required Role: ADMIN

mutation RemoveFromTeams {
  removeMemberFromTeams(userId: "user-uuid-here", teamIds: ["team-uuid-1", "team-uuid-2"]) {
    success
  }
}

Manage Team Hierarchy

Add or remove child teams to create organizational structures.

Required Role: ADMIN

# Add child teams
mutation AddChildTeams {
  addChildTeamsToTeam(
    id: "parent-team-uuid"
    childTeamIds: ["child-team-uuid-1", "child-team-uuid-2"]
  ) {
    success
  }
}

# Remove child teams
mutation RemoveChildTeams {
  removeChildTeamsFromTeam(
id: "parent-team-uuid", childTeamIds: ["child-team-uuid-1"]) {
    success
  }
}

Delete Team

Permanently delete a team.

Required Role: ADMIN

mutation DeleteTeam {
  deleteTeam(
    id: "team-uuid"
    deleteSubTeams: false
  ) {
    deleteCount
  }
}

Parameters:

id (required) - Team ID to delete
deleteSubTeams (required) - If true, recursively deletes all child teams

Warning: This operation cannot be undone. All team members will be unassigned from the team, and resource allocation rules will be deleted.

Resource Allocation Rules

Resource Allocation Rules (RARs) determine which cloud resources a team can access.Rules are composed of filters that can be combined to create precise resource matching criteria.

Understanding AND vs OR Logic

Within a Single Rule - AND Logic (Implicit)

When you specify multiple filter criteria within the same rule object, they are combined with AND logic. This means a resource must match ALL criteria to be included.

Example: Tag-Based Allocation

{
  name: "Production Environment"
  rule: {
    AND: [
      { tag: { IN: { Key: "Environment", Values: ["production"] } } }
      { tag: { IN: { Key: "Team", Values: ["platform"] } } }
    ]
  }
}

Example: Multi-Region Allocation

{
  name: "US Regions"
  rule: {
    AND: [{ region: { IN: ["us-east-1", "us-west-2"] } }]
  }
}

Across Multiple Rules - OR Logic

When you create multiple Resource Allocation Rules for a team, they work with OR logic. A resource only needs to match ANY ONE of the rules to be accessible to the team.

Example: Resources matching ANY rule are included

{
  name: "Development or Staging"
  rule: {
    AND: [
      {
        OR: [
          { tag: { IN: { Key: "Environment", Values: ["development"] } } }
          { tag: { IN: { Key: "Environment", Values: ["staging"] } } }
        ]
      }
    ]
  }
}

Available Filters:

accounts - Filter by cloud account IDs
regions - Filter by cloud regions
services - Filter by cloud services
projects - Filter by project IDs
tags - Filter by resource tags (key-value pairs)
providers - Filter by cloud provider
resourceGroups - Filter by Azure resource groups
OR - Combine multiple filters with OR logic

Users API

Manage users in your organization, including their roles, team memberships, and permissions.

List Users

Retrieve all users with filtering and sorting.

Required Role: ADMIN or MEMBER

query ListUsers {
  users(
    search: "john"
    where: { role: { in: [ADMIN] }, email: { contains: "@example.com" } }
    order: [{ lastName: ASC }, { firstName: ASC }]
    offset: 0
    limit: 50
  ) {
    id
    email
    firstName
    lastName
    fullName
    role
    teams {
      id
      name
    }
    lastLoginAt
    createdAt
  }
}

Parameters:

search - Search by email or name
where - Filter criteria (email, firstName, lastName, role)
order - Sort order (by email, firstName, lastName, or role)
offset - Results to skip (for pagination)
limit - Maximum results to return

Create User

Create new users in your organization.

Required Role: ADMIN

mutation CreateUsers {
  createUser(
    input: [
      {
        email: "[email protected]"
        firstName: "John"
        lastName: "Doe"
        role: MEMBER
        teams: [{ id: "team-uuid-here" }]
        remoteAssistanceConsent: true
        silentMode: false
      }
    ]
  ) {
    success
    users {
      id
      email
      firstName
      lastName
      fullName
      role
      teams {
        id
        name
      }
    }
  }
}

Input:

email (required) - User's email address (must be unique)
firstName (required) - First name (1-256 characters)
lastName (required) - Last name (1-256 characters)
role (required) - User role (ADMIN or MEMBER)
teams (optional) - Teams to assign user to
remoteAssistanceConsent (required) - Remote assistance consent
silentMode (optional) - If true, skip sending invitation email

Update User

Update an existing user's information.

Required Role: ADMIN

mutation UpdateUser {
  updateUser(
    userId: "user-uuid-here"
    input: { firstName: "Jane", lastName: "Smith", role: ADMIN, remoteAssistanceConsent: true }
  ) {
    success
    user {
      id
      firstName
      lastName
      role
    }
  }
}

Note: Email addresses cannot be changed through this mutation.

Delete User

Permanently remove a user from the organization.

Required Role: ADMIN

mutation DeleteUser {
  deleteUser(userId: "user-uuid-here") {
    success
    user {
      id
      email
      firstName
      lastName
    }
  }
}

Restrictions:

Cannot delete yourself
Cannot delete the last admin in the organization

Effects:

User is permanently removed
User is removed from all teams
API keys are revoked
Activity history is preserved for audit

Advanced Topics

Pagination

Most list queries support offset/limit pagination:

# First page
query FirstPage {
  opportunities(limit: 20, offset: 0) {
    id
    name
  }
}

# Second page
query SecondPage {
  opportunities(limit: 20, offset: 20) {
    id
    name
  }
}

Best Practice: Use a page size of 20-100 for optimal performance.

Filtering

The API supports powerful filtering capabilities:

String Filters:

name: {
  EQ: "Exact match"
  LIKE: "Contains (case-sensitive)"
  ILIKE: "contains (case-insensitive)"
  IN: ["value1", "value2"]
}

Numeric Filters:

savingAmount: {
  GT: 100        # Greater than
  GTE: 100       # Greater than or equal
  LT: 1000       # Less than
  LTE: 1000      # Less than or equal
  EQ: 500        # Equal
}

Date Filters:

createdAt: {
  GTE: "2024-01-01T00:00:00Z"
  LTE: "2024-12-31T23:59:59Z"
}

Complex Filters:

where: {
  OR: [
    { savingAmount: { GTE: 1000 } }
    { 
      AND: [
        { savingAmount: { GTE: 500 } }
        { risk: { LTE: 3 } }
      ]
    }
  ]
  NOT: { status: { EQ: DISMISSED } }
}

Error Handling

All API responses follow standard GraphQL error formatting:

{
  "errors": [
    {
      "message": "Error description",
      "path": ["fieldName"],
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

Common Error Codes:

VALIDATION - Input validation failed
UNAUTHENTICATED - Invalid or missing authentication token
FORBIDDEN - Insufficient permissions
NOT_FOUND - Referenced entity doesn't exist
CONFLICT - Duplicate entity or constraint violation

Best Practices:

Always check the success field in mutation responses
Parse the errors array for detailed error information
Implement retry logic for transient failures
Validate input on the client side before sending requests
Log errors for debugging and monitoring

Common Workflows

Creating a Complete Team Structure

## Common Patterns

### 1. Creating a Complete Team Structure

```graphql
# Step 1: Create parent team
mutation {
  engineering: createTeam(input: { name: "Engineering" }) {
    id
  }
}

# Step 2: Create child teams
mutation {
  backend: createTeam(input: { name: "Backend Team" }) {
    id
  }
  frontend: createTeam(input: { name: "Frontend Team" }) {
    id
  }
}

# Step 3: Establish hierarchy
mutation {
  addChildTeamsToTeam(id: "engineering-uuid", childTeamIds: ["backend-uuid", "frontend-uuid"]) {
    success
  }
}

# Step 4: Add members
mutation {
  addMembersToTeam(id: "backend-uuid", userIds: ["user1-uuid", "user2-uuid"]) {
    success
  }
}

Bulk User Creation

mutation BulkCreateUsers {
  createUser(
    input: [
      {
        email: "[email protected]"
        firstName: "Developer"
        lastName: "One"
        role: MEMBER
        teams: [{ id: "backend-team-uuid" }]
        remoteAssistanceConsent: true
      }
      {
        email: "[email protected]"
        firstName: "Developer"
        lastName: "Two"
        role: MEMBER
        teams: [{ id: "frontend-team-uuid" }]
        remoteAssistanceConsent: true
      }
    ]
  ) {
    success
    users {
      id
      email
      teams {
        name
      }
    }
  }
}

Finding High-Value Opportunities

# Query opportunities with filters
query FindHighValueOpportunities {
  opportunities(
    where: {
      status: { EQ: OPEN }
      savingAmount: { GTE: 500 }
      risk: { LTE: 3 }
    }
    orderBy: [{ savingAmount: DESC }]
    limit: 20
  ) {
    id
    name
    savingAmount
    risk
    resource {
      name
      service
    }
  }
}

# Export filtered opportunities
query ExportOpportunities {
  opportunitiesExport(
    where: {
      status: { EQ: OPEN }
      savingAmount: { GTE: 500 }
    }
    exportType: CSV
  )
}