The GreyMatter API provides access to select GreyMatter capabilities through a GraphQL interface. All API interactions occur over a secure HTTPS connection to a single endpoint. Requests are made using the POST HTTPS method with JSON-encoded bodies, and the API returns JSON-encoded responses. We use standard HTTP response codes for indicating the status of requests, and authentication is managed via API keys.
You can use GraphQL queries to fetch specific information and mutations to perform actions. To explore the full range of available operations and data structures, the API supports GraphQL introspection. As we iteratively enhance the API, introspection is the best way to stay updated on the latest features.
\nProduction Environment - https://greymatter.myreliaquest.com/graphql
Requests to all GraphQL nodes require authentication by using a dedicated (high entropy) API key. To authenticate your requests, include a header in the HTTPS request called X-API-KEY with the value of your API key.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
\nNote: You cannot use your normal email/password login details.
\nGenerating an API Key:
\nNavigate to GreyMatter > Settings > API Key Management.
\nClick the “New API Key” button in the top right corner.
\nSelect an Expiration Date (default is 1 year) and then click the “Create Key” button.
\nThe generated Key will be displayed. This is the only time the key will be visible.
\nAfter closing the prompt, you will be redirected to the API Key Management screen, which shows the key's expiration date, creation date, last query, and last usage time.
\nRemoving an API Key:
\nNavigate to GreyMatter > Settings > API Key Management.
\nClick the “Remove” button next to the API key you wish to remove.
\nSelect “Confirm”.
\nThe GreyMatter API uses GraphQL. All requests must use the POST HTTPS method.
Learning GraphQL: A good resource for learning how to query a GraphQL API is https://graphql.org/learn/queries/.
\nGraphQL Introspection: Introspection is available, allowing you to query the API to discover available queries, mutations, types, enums, etc.
\nAll operations will respond with standard HTTPS status codes:
\n2xx codes indicate successful operations.
4xx codes indicate a problem with the request (e.g., a required parameter was omitted).
5xx codes indicate a problem on the server side.
The GreyMatter API employs rate limiting to ensure performant access for all users. The limit per GreyMatter User account is 5000 tokens per hour. Each Node entity in the request counts as a token.
\nFor queries that return paginated results, the API follows the GraphQL Connections standard (https://relay.dev/graphql/connections.htm).
\nPaginated queries accept two inputs:
\nfirst: (Integer) Determines the number of results to return.
after: (String) A cursor value that determines where to start returning results. This is optional if you want to retrieve results from the beginning.
The response for a paginated query will be a Connection type, which includes:
pageInfo: Contains details on whether there is a previous or next page of data.
edges: An array containing the actual data. Each entry in edges includes a cursor property that can be used as the after input to retrieve the next page of data.
totalCount: The total number of items that matched the query.
The GreyMatter API uses Global IDs to identify entities.
\nGlobal IDs are a base64-encoded string that includes the type of entity and its unique identifier.
\nFor example, Incident:ffb4f0e4-b48d-4cb6-bf85-b9e5f27d2b27 | base64 = SW5jaWRlbnQ6ZmZiNGYwZTQtYjQ4ZC00Y2I2LWJmODUtYjllNWYyN2QyYjI3
In general, a query that returns an entity will include an id field that contains the Global ID of the entity.
Note: If a cursor is passed in that would fit inside of a page (based on the after input), the results will start at the beginning of that page, not specifically where the cursor points within the page.
If you require support for using the API, troubleshooting, or setup, please contact greymattersupport@reliaquest.com.
Q: Who Can Utilize the GM API?
\nQ: How Do I Get an API Key?
\nQ: How Many API Keys Can I Generate?
\nQ: Do API Keys Expire?
\nQ: How do I renew an API key?
\nQ: Will I be notified before my API key expires?
\nQ: Will I be notified if someone from my organization creates/renews an API?
\nQ: How does ReliaQuest store API keys?
\nQ: What is the Base URL for the API?
\nhttps://greymatter.myreliaquest.com/graphqlQ: Which Queries/Mutations will be available?
\nQ: Who can I contact if I have a support question for the GreyMatter API?
\ngreymattersupport@reliaquest.com.Q: How can I aggregrate data across multiple company entities?
\nx-reliaquest-customer and the value from customer headerSlug to pull data across entities.Create an access group
\nInputs: \nCreateAccessGroupInput,
\nReturn: \nCreateAccessGroupResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"b8b5125b-41b5-4694-a033-af943f5815df","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation createAccessGroup ($after: String, $filter: PodFilter, $first: Int, $order: PodOrder, $after1: String, $filter1: RoleFilter, $first1: Int, $order1: RoleOrder, $after2: String, $filter2: UserFilter, $first2: Int, $order2: UserOrder, $input: CreateAccessGroupInput!) {\n createAccessGroup (input: $input) {\n accessGroup {\n createdAt\n description\n id\n isDefault\n name\n pods (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n roles (after: $after1, filter: $filter1, first: $first1, order: $order1) {\n totalCount\n }\n ssoGroups\n updatedAt\n users (after: $after2, filter: $filter2, first: $first2, order: $order2) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"accessGroups\": [\n \"Create a pod
\nInputs: \nCreatePodInput,
\nReturn: \nCreatePodResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"93334142-7d8f-4f80-8150-39dd3f0d6f2a","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation createPod ($after: String, $filter: AccessGroupFilter, $first: Int, $order: AccessGroupOrder, $after1: String, $filter1: CustomerFilter, $first1: Int, $notFilter: CustomerFilter, $order1: CustomerOrder, $after2: String, $filter2: UserFilter, $first2: Int, $order2: UserOrder, $input: CreatePodInput!) {\n createPod (input: $input) {\n pod {\n accessGroups (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n createdAt\n customers (after: $after1, filter: $filter1, first: $first1, notFilter: $notFilter, order: $order1) {\n totalCount\n }\n description\n id\n name\n updatedAt\n users (after: $after2, filter: $filter2, first: $first2, order: $order2) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"customers\": [\n \"Create a role
\nInputs: \nCreateRoleInput,
\nReturn: \nCreateRoleResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"22f4d84c-dc56-4bc9-8ce8-7868ce0f046f","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation createRole ($after: String, $filter: AccessGroupFilter, $first: Int, $order: AccessGroupOrder, $after1: String, $filter1: UserFilter, $first1: Int, $order1: UserOrder, $input: CreateRoleInput!) {\n createRole (input: $input) {\n role {\n accessGroups (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n createdAt\n description\n id\n name\n permissions\n type\n updatedAt\n users (after: $after1, filter: $filter1, first: $first1, order: $order1) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"customers\": [\n \"Delete an access group
\nInputs: \nID,
\nReturn: \nDeleteAccessGroupResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"921c1225-1f22-4988-b87d-a2e3c3780f2b","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation deleteAccessGroup ($id: ID!) {\n deleteAccessGroup (id: $id) {\n success\n }\n}","variables":"{\n \"id\": \"Delete a pod
\nInputs: \nID,
\nReturn: \nDeletePodResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"e150625d-f9c6-471c-b309-8ab5efd13a10","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation deletePod ($id: ID!) {\n deletePod (id: $id) {\n success\n }\n}","variables":"{\n \"id\": \"Delete a pod
\nInputs: \nID,
\nReturn: \nDeleteRoleResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"f0489917-9d13-4d15-a336-ac42a1354dab","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation deleteRole ($id: ID!) {\n deleteRole (id: $id) {\n success\n }\n}","variables":"{\n \"id\": \"Update an access group
\nInputs: \nUpdateAccessGroupInput,
\nReturn: \nUpdateAccessGroupResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"1a26210b-bb61-4e4e-a7c6-e36acdf63e51","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation updateAccessGroup ($after: String, $filter: PodFilter, $first: Int, $order: PodOrder, $after1: String, $filter1: RoleFilter, $first1: Int, $order1: RoleOrder, $after2: String, $filter2: UserFilter, $first2: Int, $order2: UserOrder, $input: UpdateAccessGroupInput!) {\n updateAccessGroup (input: $input) {\n accessGroup {\n createdAt\n description\n id\n isDefault\n name\n pods (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n roles (after: $after1, filter: $filter1, first: $first1, order: $order1) {\n totalCount\n }\n ssoGroups\n updatedAt\n users (after: $after2, filter: $filter2, first: $first2, order: $order2) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"accessGroups\": [\n \"Update a pod
\nInputs: \nUpdatePodInput,
\nReturn: \nUpdatePodResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"d1f6ede3-8226-42f2-8a21-467c83ee9fed","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation updatePod ($after: String, $filter: AccessGroupFilter, $first: Int, $order: AccessGroupOrder, $after1: String, $filter1: CustomerFilter, $first1: Int, $notFilter: CustomerFilter, $order1: CustomerOrder, $after2: String, $filter2: UserFilter, $first2: Int, $order2: UserOrder, $input: UpdatePodInput!) {\n updatePod (input: $input) {\n pod {\n accessGroups (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n createdAt\n customers (after: $after1, filter: $filter1, first: $first1, notFilter: $notFilter, order: $order1) {\n totalCount\n }\n description\n id\n name\n updatedAt\n users (after: $after2, filter: $filter2, first: $first2, order: $order2) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"customers\": [\n \"Update a pod
\nInputs: \nUpdateRoleInput,
\nReturn: \nUpdateRoleResponse
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"see GreyMatter - Global Settings - API to create a valid API Key"}]},"isInherited":true,"source":{"_postman_id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","id":"25ab67c1-bb92-4953-90b0-d0ef02c682b1","name":"GreyMatter API","type":"collection"}},"urlObject":{"host":["https://greymatter.myreliaquest.com/graphql"],"query":[],"variable":[]}},"response":[{"id":"131c66c1-6085-46ca-b43e-53d868137c73","name":"response","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"query":"mutation updateRole ($after: String, $filter: AccessGroupFilter, $first: Int, $order: AccessGroupOrder, $after1: String, $filter1: UserFilter, $first1: Int, $order1: UserOrder, $input: UpdateRoleInput!) {\n updateRole (input: $input) {\n role {\n accessGroups (after: $after, filter: $filter, first: $first, order: $order) {\n totalCount\n }\n createdAt\n description\n id\n name\n permissions\n type\n updatedAt\n users (after: $after1, filter: $filter1, first: $first1, order: $order1) {\n totalCount\n }\n }\n success\n }\n}","variables":"{\n \"after\": \"T18w\",\n \"filter\": {\n \"customers\": [\n \"