> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1.md). # API v1 ## Why use Material APIs? The Material Security APIs give you programmatic access to the threat detection and email analysis data inside Material, so you can act on it outside the product. One common use for the APIs is to integrate Material with a SOAR platform or other security tooling. For example, you can use the Issues API to list open issues, match them against signals in your existing workflows, and fetch full issue details, including related messages, accounts, and files, to enrich an incident or trigger a response action. More broadly, the APIs are useful any time your team needs to analyze, export, or operationalize Material data in an external system. {% hint style="success" %} ### What is Material API v1? This API isn't just a new version of our beta API. We built API v1 from scratch around how developers actually use an API. It covers Email Threat investigation and response end to end, along with the accounts, groups, roles, OAuth apps, and trusted entities behind them. **Note:** The beta API remains available as-is for the foreseeable future. We won't break what you've already built. New release improvements will focus on API v1. [Beta API documentation ](/reference/beta-api-and-event-descriptions.md)is still available in the app. {% endhint %} *** ## Resources Overview The Material Security API v1 includes these resources: **Issues**, **Messages**, **Accounts**, **Groups**, **Roles**, **OAuth Apps**, and **Trusted Entities**. {% hint style="info" %} The Material Security API is growing fast. We're actively adding new resources. We'll let you know as they're released in What's New. What do you want to see added next? Contact support to let us know. {% endhint %}
Issues An issue represents a detected threat or anomaly in your environment. Issues are created automatically when Material's detections fire, and track the full lifecycle of a threat, from initial detection through investigation and resolution. Each issue includes a severity level, classification, and a reference to the primary entity involved, such as an account, message, or file. Use the Issues API to query and filter issues by status, retrieve full issue details, and fetch the email messages at the center of each threat.
Messages A message represents an email ingested and analyzed by Material. Messages are the primary evidence attached to most issues, and can be retrieved individually or searched across in bulk using MQL (Material Query Language). Use the Messages API to retrieve a specific message by ID, or run an asynchronous search to find messages matching criteria such as sender, subject, or date range.
Accounts An account represents a directory account synced from Google Workspace or Microsoft 365. Each one carries its VIP designation, licenses, effective settings and the level each value comes from, mailbox state, provider status, and role assignments. Use the Accounts API to list and filter accounts, retrieve a single account along with its group memberships, and update VIP designation, licenses, per-account setting overrides, and role assignments, either one account at a time or in bulk.
Groups A group represents a directory group synced from your provider, including Google groups and org units, Microsoft groups, and Okta groups. Each one carries licenses, per-group setting overrides, and the roles it grants its members. Use the Groups API to list and filter groups, retrieve a single group, list the accounts that belong to it, and update groups either one at a time or in bulk.
Roles A role determines what an admin can do in Material. Role definitions are built in, so you manage assignments rather than the roles themselves. Use the Roles API to list the roles you can assign on your instance, then assign them by updating an account or a group.
OAuth Apps An OAuth app represents a third-party app holding token grants in your Google Workspace tenant, along with the scopes it was granted, its classification, and its standing remediation policy. Use the OAuth Apps API to list and filter apps, retrieve a single app with its investigation results, list the accounts that granted it, update its classification and remediation, and revoke an individual account's grant.
Trusted Entities A trusted entity is a domain, email address, or IP address or CIDR range that your instance treats as trusted. Use the Trusted Entities API to review what your instance already trusts, then add, retrieve, update, and delete the entities you manage.
*** ## Material API v1 Guides
🔐 AuthenticationHow to get an API tokenAuthentication
🌎 Hello WorldWalkthroughs for your first calls to every API v1 resourceHello World
⁉️ Errors and TroubleshootingLogging, tokens, and FAQsErrors and Troubleshooting
API ReferenceThe complete technical specification for Material API V1, covering every endpoint, request parameter, response object, and field, including valid values, data types, and formats.Broken link
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.material.security/reference/api-v1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.