API Reference

Every request (except health checks) requires a Bearer token. All responses are JSON.

On this page

Authentication

How to create, use, and manage API tokens.

All API endpoints (except GET /api/v1/health) require a valid Bearer token. Tokens are created through Settings → API Tokens in the web UI.

Creating a token

  1. Navigate to Settings → API Tokens in the web UI.
  2. Enter a token name and choose a scope (read or read_write).
  3. Click Create to generate the token.

Token values are shown only once at creation time. Be sure to copy and store them securely.

Token format

Tokens are 128 hex-character strings with a ms_ prefix:

<example>: ms_3c5a7f9b1e4d8c0a6f2e3b9d8c7a6f5e4d3c2b1a09876543210abcdef123456

Token scopes

Scope Description
“read” Read-only access. Accepts GET endpoints only.
“read_write” Full access. Accepts all endpoints including POST, PUT, PATCH, and DELETE.

Including the token in requests

Send the token in the Authorization header as a Bearer token:

Authorization: Bearer ms_3c5a7f9b1e4d8c0a6f2e3b9d8c7a6f5e4d3c2b1a09876543210abcdef123456

Memories

Create, read, update, and delete memories in your family.

GET /api/v1/memories read scope

List memories for the authenticated user’s family, with cursor-based pagination.

Parameters

Param Description
cursor Pagination cursor from a previous next_cursor meta value.
per_page Number of results per page (1–100, default 25).
q Full-text search query across memory content.

Response

{
   "data": [
     { "id": 1, "family_id": 1, "created_by_user_id": 1, "title": "...", "transcript": "...",
       "notes": "...", "recorded_at": "2025-01-01T00:00:00Z", "location_name": "...",
       "tags": [], "visibility": "visible", "transcription_status": "pending",
       "ai_data": null, "ai_extraction_status": null,
       "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-01T00:00:00Z" }
   ],
   "meta": {
     "next_cursor": "cmVjb3JkZWQtYXQtdXVpZD18MQ==",
     "total_count": 42
   }
}
GET /api/v1/memories/:id read scope

Return a single memory’s details.

Response

{
   "data": {
     "id": 1,
     "family_id": 1,
     "created_by_user_id": 1,
     "title": "...",
     "transcript": "...",
     "notes": "...",
     "recorded_at": "2025-01-01T00:00:00Z",
     "location_name": "...",
     "tags": [],
     "visibility": "visible",
     "transcription_status": "pending",
     "ai_data": null,
     "ai_extraction_status": null,
     "created_at": "2025-01-01T00:00:00Z",
     "updated_at": "2025-01-01T00:00:00Z"
   }
}
POST /api/v1/memories write scope

Create a new memory. Returns 201 Created.

Accepted params

Param Description
audioAudio file blob (mutually exclusive with transcript).
recorded_atWhen the memory was recorded.
duration_secondsAudio duration in seconds.
transcript_languageLanguage of the transcript.
transcriptText transcript (mutually exclusive with audio).
titleMemory title.
notesNarrative notes.
location_nameLocation name.
visibilityVisibility state.
pinnedPin the memory.
tags[]Array of tags.

Response (201)

{
   "data": {
     "id": 1,
     "family_id": 1,
     "created_by_user_id": 1,
     ...
   }
}
PUT /api/v1/memories/:id write scope

Update an existing memory. Returns 200 OK.

Accepted params

Param Description
titleMemory title.
notesNarrative notes.
recorded_atWhen the memory was recorded.
visibilityVisibility state.
pinnedPin the memory.
tags[]Array of tags.

Response (200)

{
   "data": {
     "id": 1,
     ...
   }
}
DELETE /api/v1/memories/:id write scope

Delete a memory. Audio attachments are purged.

Response

204 No Content

Tokens

Manage API tokens programmatically.

GET /api/v1/tokens read scope

List active (non-revoked) API tokens for the user's family.

Response

{
    "data": [
      {
        "id": 1,
        "name": "Mobile App",
        "scope": "read_write",
        "family_id": 1,
        "last_used_at": "2025-01-01T00:00:00Z",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
}
POST /api/v1/tokens write scope

Create a new API token. Returns 201 with a one-time token field.

Accepted params

Param Description
token[name]Token name (max 100 chars).
token[scope]Scope: read or read_write.

Response (201)

{
    "data": {
      "id": 1,
      "name": "Mobile App",
      "scope": "read_write",
      "family_id": 1,
      "last_used_at": null,
      "created_at": "2025-01-01T00:00:00Z",
      "token": "ms_3c5a7f9b1e4d8c0a6f2e3b9d8c7a6f5e4d3c2b1a09876543210abcdef123456"
    }
}

token is shown only once.

DELETE /api/v1/tokens/:id write scope

Revoke an active API token.

Response

204 No Content
POST /api/v1/tokens/:id/rotate write scope

Rotate a token. Returns the new raw token once.

Response

{
    "data": {
      "id": 1,
      "name": "Mobile App",
      "scope": "read_write",
      "family_id": 1,
      "last_used_at": null,
      "created_at": "2025-01-01T00:00:00Z",
      "token": "ms_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
    }
}

Family

Manage family members and send invitations.

GET /api/v1/family/members read scope

List all members of the authenticated user's family.

Response

{
     "data": [
       {
         "id": 1,
         "user_id": 1,
         "name": "Jane Doe",
         "email": "jane@example.com",
         "role": "owner",
         "joined_at": "2025-01-01T00:00:00Z"
       }
     ]
}
PATCH /api/v1/family/members/:id write scope + admin/owner

Update a family member's role. Requires admin or owner role.

Accepted params

Param Description
roleNew role: owner, admin, or member.

Response (200)

{
     "data": {
       "id": 1,
       "user_id": 1,
       "name": "Jane Doe",
       "email": "jane@example.com",
       "role": "admin",
       "joined_at": "2025-01-01T00:00:00Z"
     }
}
DELETE /api/v1/family/members/:id write scope + admin/owner

Remove a family member. Cannot remove yourself.

Response

204 No Content
POST /api/v1/family/invitations write scope

Send an invitation to join the family. An email is sent to the invitation address.

Accepted params

Param Description
invitation[email]Email address of the person to invite.
invitation[role]Role to assign: owner, admin, or member.

Response (201)

{
     "data": {
       "id": 1,
       "email": "invitee@example.com",
       "role": "member",
       "status": "pending"
     }
}

Health

Check API availability without authentication.

Health

GET /api/v1/health

No authentication required. Returns a JSON body confirming the API is operational.

Response

{
  "status": "ok"
}

Error Responses

Standard error formats returned by all endpoints.

Error Responses

All API errors follow a consistent JSON structure with an error or errors object.

Single errors

Returned for authentication failures, forbidden access, and general errors.

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

Validation errors

Returned when request body parameter validation fails. Fields are keyed by attribute.

{
  "errors": {
    "field": ["message"]
  }
}