API reference

API Introduction

Mortimer includes an HTTP API for programmatic access from scripts, CLIs, and custom apps.

This page shows the fastest path from zero to your first authenticated API call.

Quickstart in 60 seconds

Replace <your-host>, <tenant_slug>, and <api_token> with your values.

  1. Check API availability:
curl "https://<your-host>/api/v1/contract" -H "Accept: application/json"
  1. Create an API key (while signed in with your web session):
curl -X POST "https://<your-host>/<tenant_slug>/api_keys" \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-b "<browser_session_cookie>" \
	-d '{"api_key":{"name":"CLI key"}}'

The browser session cookie is created automatically when you log in to Mortimer. For manual curl testing, advanced users can copy it from browser developer tools. Treat it like a password and do not share it.

  1. Call an authenticated endpoint:
curl "https://<your-host>/api/v1/identity" \
	-H "Authorization: Bearer <api_token>" \
	-H "Accept: application/json"

Prepare

Before you start, make sure you have:

  1. A user account in Mortimer.
  2. Access to at least one tenant.
  3. A valid web login session in your browser.
  4. Your tenant slug (the value used in /:tenant_slug/... URLs).

Recommended path: open the user menu and go to API Keys to create/revoke keys in the UI. Use those keys as bearer tokens for /api/v1 requests.

Authenticate

Mortimer API authentication uses opaque bearer tokens (API keys). A key is only shown once when created.

1) Create an API key

While signed in to Mortimer in the browser session, create a key:

curl -X POST "https://<your-host>/<tenant_slug>/api_keys" \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-b "<browser_session_cookie>" \
	-d '{
		"api_key": {
			"name": "CLI key",
			"expires_at": "2026-12-31T23:59:59Z"
		}
	}'

The session cookie used above is your normal logged-in browser cookie. It is not an API token, and it should not be distributed to other users or systems.

The response includes:

  • data.token (raw key, shown once)
  • data.token_prefix (safe identifier)
  • metadata such as expires_at and created_at

Store data.token securely (password manager or secrets manager).

2) Use bearer auth

Use the token in the Authorization header:

curl "https://<your-host>/api/v1/identity" \
	-H "Authorization: Bearer <api_token>" \
	-H "Accept: application/json"

JavaScript example

const response = await fetch("https://<your-host>/api/v1/identity", {
	method: "GET",
	headers: {
		"Accept": "application/json",
		"Authorization": `Bearer ${process.env.MORTIMER_API_TOKEN}`
	}
});

if (!response.ok) {
	const error = await response.json();
	throw new Error(error?.error?.message || "API request failed");
}

const payload = await response.json();
console.log(payload.data);

Endpoints

Start with these core endpoints:

  1. GET /api/v1/contract
  • Public contract baseline endpoint.
  1. GET /api/v1/identity
  • Requires bearer token.
  • Returns identity, tenant, and membership context for the token.
  1. GET /api/v1/teams
  • Requires bearer token.
  • Returns tenant-scoped teams with optional q, page, and per_page params.
  • per_page defaults to 20 and is capped at 50.
  1. POST /api/v1/teams, PATCH /api/v1/teams/:id, DELETE /api/v1/teams/:id
  • Requires bearer token and admin membership.
  • Supports create/update/delete with standard error outcomes (401/403/404/422).
  1. GET /api/v1/widgets
  • Requires bearer token.
  • Returns tenant-scoped widgets with optional q, page, and per_page params.
  • per_page defaults to 20 and is capped at 50.
  1. POST /api/v1/widgets, PATCH /api/v1/widgets/:id, DELETE /api/v1/widgets/:id
  • Requires bearer token and admin membership.
  • Supports create/update/delete with standard error outcomes (401/403/404/422).
  1. GET /:tenant_slug/api_keys
  • Requires normal signed-in web session.
  • Lists your API keys for the tenant.
  1. POST /:tenant_slug/api_keys
  • Requires normal signed-in web session.
  • Creates a key and returns the raw token once.
  1. DELETE /:tenant_slug/api_keys/:id
  • Requires normal signed-in web session.
  • Revokes a key.

To discover additional API endpoints as they are released:

  • Check the OpenAPI root: docs/openapi/openapi.yaml
  • Follow path references under docs/openapi/paths/
  • Reuse component schemas under docs/openapi/components/schemas/
  • Use the path-level examples blocks in OpenAPI for copy-ready request and response payloads.

Getting help

If a request fails, check these first:

  1. Missing or malformed Authorization: Bearer <token> header.
  2. Expired or revoked API key.
  3. Wrong tenant slug for key-management endpoints.
  4. Missing Content-Type: application/json on JSON requests.

If you still need help, include request method, endpoint, status code, and response body when asking for support.

Submit an issue

When reporting an API issue, include:

  1. Exact endpoint and HTTP method.
  2. Sanitized request headers/body (never include raw API keys).
  3. Full response status and body.
  4. Timestamp and tenant slug.
  5. Expected behavior vs actual behavior.

Join the community

Join your project or team communication channel and share reproducible API examples. Short curl commands and sanitized payloads usually lead to faster help.

Previous
Extending Mortimer
Next
Authentication