> 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.

What's here now is just the beginning. We started with Email Threat use cases because that's what customers do most often, and we wanted to make it available as soon as it was ready. We plan to keep adding more endpoints and resources to API v1 — and we'd love your feedback on what to build next. Contact support and let us know what you want to see.

**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 currently includes two resources: **Issues** and **Messages**.

{% 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](https://docs.material.security/whats-new).\
\
What do you want to see added next? Contact support to let us know.
{% endhint %}

<details>

<summary>Issues</summary>

An issue represents a detected threat or anomaly in your environment. Issues are created automatically when Material's detection rules 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.

</details>

<details>

<summary>Messages</summary>

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.

</details>

***

## Material API v1 Guides

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1f510">🔐</span> <strong>Authentication</strong></td><td>How to get an API token</td><td></td><td></td><td><a href="/pages/qXHYF45uKxJceZak9qtv">/pages/qXHYF45uKxJceZak9qtv</a></td></tr><tr><td>🌎 <strong>Hello World</strong></td><td>Walkthroughs for your first calls to Issues and Messages</td><td></td><td></td><td><a href="/pages/hxIwg2YA56D5RB9UpBCM">/pages/hxIwg2YA56D5RB9UpBCM</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="2049">⁉️</span> <strong>Errors and Troubleshooting</strong></td><td>Logging, tokens, and FAQs</td><td></td><td></td><td><a href="/pages/Rj79H7t3uDtXkZME63bg">/pages/Rj79H7t3uDtXkZME63bg</a></td></tr><tr><td><strong>API Reference</strong></td><td>The complete technical specification for Material API V1, covering every endpoint, request parameter, response object, and field — including valid values, data types, and formats.</td><td><a href="/pages/xfkLV3hdyh9d0Dkw01TV#issues">/pages/xfkLV3hdyh9d0Dkw01TV#issues</a></td><td><a href="/pages/xfkLV3hdyh9d0Dkw01TV#messages">/pages/xfkLV3hdyh9d0Dkw01TV#messages</a></td><td><a href="/pages/055003f132e75e181b24bb0b7c1cce498e7bfaf6">/pages/055003f132e75e181b24bb0b7c1cce498e7bfaf6</a></td></tr></tbody></table>


---

# 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=<question>&goal=<endgoal>
```

`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.