Version: 1.0

Memfault API Documentation

About

This is the documentation for the Memfault REST API.

For CI & scripting, we recommend using the Memfault CLI Tool which exposes an easy to use interface for a majority of the REST APIs detailed below.

Linked below are other useful resources:

• Firmware SDK Documentation
• Guide: Data From Firmware To The Cloud
• Memfault Keyword Terminology
• HTTP Response Status Codes

Memfault URLs

There are four API related URLs that will be used with Memfault's service. The proper use for each is as follows:

• api.memfault.com - Use along with an API Key for normal consumption and use of the API documented below.
• chunks.memfault.com - Use with the Chunks API to push chunked data into Memfault.
• ingress.memfault.com - Use with APIs that push data into Memfault, such as Events and Coredumps.
• files.memfault.com - Use in Continuous Integration systems for uploading large files, such as binaries, symbol files, bugreports, etc.

Authentication

There are four ways to authenticate when interfacing with the Memfault API.

Email + Password

To test if the Email + Password works, one can try this example request

curl --user user@example.com:mypassword https://api.memfault.com/auth/me

where user@example.com is the User's email and mypassword is the User's password

Email + API Key

Please refer to the section 'Auth -> Generate User API Key' to learn how to get an API key. Once one is generated, the user can authenticate with the email + API key combination using Basic Auth.

To test if the Email + API Key works, one can try this example request

curl --user user@example.com:123e4567e89b12d3a456426655440000 https://api.memfault.com/auth/me

where user@example.com is the User's email and 123e4567e89b12d3a456426655440000 is the User's API Key

Organization Auth Token

Organization Auth Tokens allow access of the organization's resources for automation. They can be accessed and managed by Administrators at Admin → Organization Auth Tokens in the Memfault UI.

Organization Auth Tokens use Bearer Authentication.

To test if the Organization Auth Token works, one can try this example request

curl --header "Authorization: Bearer oat_123e4567e89b12d3a456426655440000" https://api.memfault.com/api/v0/organizations

Memfault Project Key

This is only for use when pushing data into Memfault, or by a Device that may have limited memory when accessing specific endpoints (such as the Latest Release endpoint).

This sort of authentication will not work with most API endpoints. API endpoints that accept or require this form of authentication will explicitly say so in their specific documentation.

This enables Devices to associate directly to a Project instead of with a particular User, Memfault account, or API Key. It also allows for a shorter URL which doesn't have to specify the Project or Organization. Devices can make requests such as:

curl \
  https://ingress.memfault.com/api/v0/events \
  -H "Memfault-Project-Key: 06e7916f2db44167a1f5196cfe83a898" \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

The Memfault Project Key for a Project can be found in the Dashboard under Settings.

Requests

All API data sent and received is JSON.

Methods

Method	Example Route	Count	Description
GET	/objects	many	Get a list of the objects
GET	/objects/:key	single	Get a single object
POST	/objects	single	Create a single object
PATCH	/objects/:key	single	Update any number of fields in an object
PUT	/objects/:key	single	Create/Update a relationship object
DELETE	/objects	many	Delete many objects (sent as JSON data)
DELETE	/objects/:key	single	Delete a single object

NOTE: Not all routes implemented for all types. Please reference the documentation for exact routes and features.

Parameters

Most endpoints with methods of type POST, PATCH, and PUT will accept parameters and data in JSON format.

Header: Content-Type: application/json

Query Parameters & Filtering

Many API endpoints allow filtering of the results through the use of query parameters. These are optional and URL encoded. The list of possible parameters are listed under each route. Many of them accept list of values, in the following format:

ex. single Cohort

/issues?cohort=alpha

ex. List of Cohorts

/issues?cohort=alpha&cohort=beta&cohort=internal

Query Parameters that accept lists are denoted by the [] signifier after their name in the documentation for each endpoint. ex. cohorts[]

Timestamps

When sending timestamps in requests as parameters, such as for created_date or first_seen, ISO 8601 standard with a Z is required.

Valid for requests: 2025-02-27T00:00:00Z

Not valid for requests (will return 'Not a valid datetime'):

• 2025-02-27
• 2025-02-27T00:00:00+00:00

Sorting

For all sort parameters, you may include - to force Descending sort, or leave it off to force Ascending sort.

The following will sort by created_date descending, with the newest entries last.

/projects?sort=-created_date

The following will sort by created_date ascending, with the newest entries first.

/projects?sort=created_date

Pagination

Pagination works on every endpoint, and the following parameters can be passed in to manipulate the page and size of each request.

Query String Parameter	Required	Description
page	optional	Page number of the result set (default: 1)
per_page	optional	Limit the number of results per page. (default: 20, max: 100)

Example:

curl -X GET "https://api.memfault.com/api/v0/organizations/memfault/projects/demo/events?per_page=10&page=2"

Versions

All Versions are required to be Semantic Versions.

Responses

Pagination

On responses where multiple items could be returned, a paging field in the JSON object is returned.

{
  "data": {
    "..."
  },
  "paging": {
    "item_count": 35,
    "page": 1,
    "page_count": 1,
    "per_page": 20,
    "total_count": 35
  }
}

Field	Type	Description
item_count	Number	Number of items returned in this response
total_count	Number	Number of items total on server that could be returned
page	Number	The current page number
page_count	Number	The number of pages that could be returned from the server
per_page	Number	The maximum number of items that will be returned in a response

Schema

Timestamps are returned in ISO 8601 format.

2014-12-22T03:12:58.019077+00:00

Memfault Resources

The following is a table of all Memfault Resources and their identifiers, URIs, and notes about each of them.

Resource	Identifier Type	API URI	Notes
Organization	slug	/organizations/<organization_slug>	Max Length: 128 Regex: [-a-zA-Z0-9_]+
Project	slug	/organizations/<organization_slug>/projects/<project_slug>	Max Length: 128 Regex: [-a-zA-Z0-9_]+
Release	slug	/organizations/<organization_slug>/projects/<project_slug>/releases/<release_version>	Max Length: 128 Regex: [-a-zA-Z0-9_.+]+
Cohort	slug	/organizations/<organization_slug>/projects/<project_slug>/cohorts/<cohort_slug>	Max Length: 128 Regex: [-a-zA-Z0-9_]+
Device	slug	/organizations/<organization_slug>/projects/<project_slug>/devices/<device_serial>	Max Length: 128 Regex: [-a-zA-Z0-9_]+
HardwareVersion	slug	N/A	Max Length: 128 Regex: [-a-zA-Z0-9_.+]+
Deployment	id	/organizations/<organization_slug>/projects/<project_slug>/deployments/<id>
Event	id	/organizations/<organization_slug>/projects/<project_slug>/events/<id>
Trace	id	/organizations/<organization_slug>/projects/<project_slug>/traces/<id>
Issue	id	/organizations/<organization_slug>/projects/<project_slug>/issues/<id>
Install	id	/organizations/<organization_slug>/projects/<project_slug>/installs/<id>

Authentication

HTTP: Basic Auth

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

HTTP: Bearer Auth

Organization Auth Token (oat_...) passed as Bearer token

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer