API Reference

Welcome to the Assumetr Public API Reference.

Our API is organized around REST. It has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Getting Started

1. Create an API client — see the Authentication Guide for creating client credentials
2. Exchange credentials for a token — use POST /v1/auth/token with client credentials
3. Make API calls — include the token as Authorization: Bearer <TOKEN>
4. Browse endpoints — see the full Interactive API Explorer

Authentication Methods

The Assumetr API supports two authentication methods:

Method	Use Case	Token Lifetime
Session tokens via POST /v1/auth/login	Browser-based dashboard access	Configurable
API client tokens via POST /v1/auth/token	CI/CD, SIEM, automation (machine-to-machine)	15 minutes

For detailed API client setup, token exchange, scopes, and curl examples, see the API Authentication Guide.

Exposure Model

Endpoints are classified by exposure tier. This documentation covers the public-preview tier only.

Tier	Meaning
public-preview	Available for external use; may have breaking changes with 30-day notice
public-ga	Fully supported public API with semantic versioning

If you inspect network traffic, you may see additional routes. Do not build external integrations against undocumented routes. They are not guaranteed to be stable and are excluded from this reference.

Base URL

All API requests should be prefixed with the following base URL:

https://api.assumetr.com

For local development:

http://localhost:8082

Rate Limits

API endpoints enforce per-IP and per-client rate limits:

Endpoint	Per-IP	Per-Client	Notes
/v1/auth/token	20/min	5/min	Exponential backoff after 3 failures
/v1/auth/login	10/min	—	Per-IP only
Other endpoints	60/min	—	Standard rate limit

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Format

All error responses follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "A human-readable error description"
  }
}

OAuth token exchange errors use the standard RFC 6749 format:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Common HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
400	Validation error — check the error.message field
401	Missing or invalid authentication
403	Insufficient permissions or scope
404	Resource not found
409	Conflict (e.g., duplicate email)
429	Rate limited — respect the Retry-After header

Next Steps

• Authentication Guide — create API clients and exchange credentials
• Interactive API Explorer — browse all endpoints with schemas and examples