> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mezmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mezmo API

> API access to Mezmo

The Mezmo API gives you programmatic control over the entire Mezmo platform — from sending and querying log data to building and managing telemetry pipelines to administering your organization at scale. Use it to ingest logs and metrics, configure processors
and pipeline nodes for real-time data transformation, set up alerts and exclusion rules to keep your data clean and actionable, export or archive logs for long-term storage and compliance, and manage accounts, members, and API keys across your enterprise.
Whether you're automating pipeline deployments, integrating Mezmo into your own tooling, or building custom dashboards on top of your telemetry data, this reference covers every endpoint you need to get started.

Download the [API Spec as OpenAPI](/apis/combined-mezmo-api.yaml).

# Authenticating With The API

When making API requests, it is crucial to authenticate them to ensure secure communication and proper authorization. Mezmo's API utilizes a key-based authentication system. This method involves including a unique access key in the Authorization header of your request, prefixed with the `Token`  scheme.

### Quick start

Add the Authorization header - Format: `Authorization: Token <your_token>`

```bash theme={null}
export $MZM_ACCESS_KEY = 'sta_1a2b3c4d5e6f7890abcdef1234567890abcdef12'

curl -H "Authorization: Token $MZM_ACCESS_KEY" \
     -H "Accept: application/json" \
     https://api.mezmo.com/v3/pipeline
```

```javascript theme={null}
const res = await fetch('https://api.mezmo.com/v3/auth/token>', {
	headers: {
		'Authorization': `Token ${process.env.MZM_ACCESS_KEY}`,
		'Accept': 'application/json'
	}
})
```

For enterprise operations, additional, specific account context may be included for delegation as needed.

1. `x-delegate-account-id: <account_id>` (enterprise tokens only)

```bash theme={null}
export MZM_ENTERPRISE_KEY = 'ste_d710b57dc7dedde45ccc4c35b68cf385b89f8dc3'

curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     -H "x-delegate-account-id: 507f1f77bc" \
     https://api.mezmo.com/v3/pipeline
```

***

### Key Considerations

Choose the Appropriate Access Key Type:

Mezmo offers different token types, each designed for specific use cases and levels of access. Carefully select the token type that best aligns with the requirements of your application or integration. This might include:

1. **Service Accounts**: Often used for machine-to-machine communication, background services, or applications that require persistent access. Service accounts have only single access key associated with it
   1. **Enterprise Service Accounts**: Similar to a standard service account with the exception that these access keys are not bound to an individual account and may be used to manage an enterprise programmatically, or interface with any of the child accounts associated with an enterprise organization.
2. **Personal Access Keys**: Associated with a specific user with in the organization which may have a shorter lifespan. These keys inherently have the level of access as the user it is associated with. Changing the permissions granted to a user changes the scope of any access keys they may have provisioned.
   1. Scoped Access: Additionally, personal access keys may be created with a limited level of access to further restrict what they may be used for.

#### Examples

```bash theme={null}
export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
export MZM_ENTERPRISE_KEY = 'ste_d710b57dc7dedde45ccc4c35b68cf385b89f8dc3'
# Account‑scoped
curl -H "Authorization: Token $MZM_ACCESS_KEY" \
     https://api.mezmo.com/v3/pipeline
     
# Enterprise‑scoped
curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     https://api.mezmo.com/v3/enterprise/account

# Delegation (enterprise keys  only)
curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     -H "x-delegate-account-id: 507f1f77bc" \
     https://api.mezmo.com/v3/pipeline
```

### Security best practices

* Rotate tokens regularly. Use expirations and rotate before they expire.
* Grant only what you need. Prefer minimal scopes.
* Use service accounts for automation. Avoid personal tokens in CI/CD.
* Store tokens in environment variables or a secret manager. Do not hard‑code tokens.
* Implement a mechanism to quickly revoke tokens if they are suspected of being compromised or are no longer needed.

```bash theme={null}
# Good
export MZM_ACCESS_KEY="sta_34b8f6897cd3396e6af781c3bfe34065b690f90b"
curl -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline

# Avoid
curl -H "Authorization: Token sta_34b8f6897cd3396e6af781c3bfe34065b690f90b" \ 
     https://api.mezmo.com/v3/pipeline
```

***

### Troubleshooting

Common HTTP codes

| Code  | Meaning                  | What to do                                             |
| ----- | ------------------------ | ------------------------------------------------------ |
| `401` | Token invalid or expired | Check token format and expiration. Re‑issue if needed. |
| `403` | Insufficient permissions | Verify the token has the required scopes.              |
| `404` | Resource not found       | Check the endpoint URL and resource IDs.               |

Quick validation

**Expect 200 (valid) or 401 (invalid)**

```bash theme={null}
export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
curl -I -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline
```

Debug headers

Responses from the API will include additional metadata in the response headers describing what the system understood about the subject making the request. The can be identified with a common prefix - `x-auth-*`

```bash theme={null}
export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
curl -v -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline
# Inspect x-auth-* headers in the response
```

```http theme={null}
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-request-id: 0e87e821-c93c-4642-a69c-8ac40478239e
x-auth-subject-id: 507f1f77bcf86cd799439015
x-auth-account-id: 507f1f77bcf86cd799439012
x-auth-enterprise-id: 68c584136b9b08b8fc53a85e
x-auth-subject-email: user@example.com
x-auth-account-short-id: d3396ea1f
x-auth-access-type: access
```