GraphQL API Reference

Pentographer exposes a GraphQL API at https://app.pentographer.com/api/graphql. You can query projects, findings, and playbooks, or perform updates programmatically. If you are new to GraphQL, read the official GraphQL documentation first.

Accessing the GraphiQL Explorer

To explore the schema interactively, open https://app.pentographer.com/api/graphql in your browser. The page loads the Yoga GraphiQL interface.

[!NOTE] If you are self-hosting, replace https://app.pentographer.com with your own deployment URL throughout this guide.

[!IMPORTANT] The GraphQL server requires authentication for all schema operations, including introspection queries. Unauthenticated requests receive a 401 Unauthorized response. To use the GraphiQL explorer, use a browser extension to append an Authorization: Bearer <token> header containing a valid API key or OAuth access token.

Authentication Header

Include your token in the HTTP header of every request:

Authorization: Bearer ptg_your_api_key_here

Example Queries

Querying User Profile

Retrieve the currently authenticated user's email:

query GetMyProfile {
  me {
    email
  }
}

Querying Projects and Findings

Retrieve a list of projects in your organization along with their status, customer details, and linked findings:

query GetProjects {
  projects {
    id
    name
    status
    customer {
      id
      name
    }
    findings {
      id
      title
      risk
      status
    }
  }
}

Querying Playbooks

List available playbooks and their underlying checklist items:

query GetPlaybooks {
  playbooks {
    id
    name
    version
    categories {
      id
      name
      items {
        id
        title
        risk
        frameworkRef
      }
    }
  }
}

Example Mutation

Creating a Finding

Create a new finding inside a specific project:

mutation CreateFinding($projectId: ID!, $title: String!, $risk: String!) {
  createFinding(input: {
    projectId: $projectId
    title: $title
    risk: $risk
  }) {
    id
    title
    risk
    status
  }
}