API access

Use your instance origin

The REST API is served by the application under /api/v1, not by this landing website. Obtain a personal access token in your account settings, keep it in a private environment or secret store, and use HTTPS outside localhost. The following example assumes MEMOS_URL and MEMOS_TOKEN are already set securely; it does not sign you in or create a token.

curl --fail-with-body \
  -H "Authorization: Bearer $MEMOS_TOKEN" \
  "$MEMOS_URL/api/v1/auth/me"

curl --fail-with-body --get \
  -H "Authorization: Bearer $MEMOS_TOKEN" \
  --data-urlencode "pageSize=20" \
  "$MEMOS_URL/api/v1/memos"

Read the exact contract

The API index lists all 92 operations in the current Rust implementation's REST contract. Each page shows its path, parameters, body and responses, with linked schema definitions. The generated contract's info.version field is a schema-generator value, not the application's 0.1.0 release number. Resource names such as memos/abc are not interchangeable with display names.

Pagination, masks and retries

Read the calling conventions and the operation-specific runtime notes before implementing pagination or PATCH. Some small collections ignore pagination inputs; UpdateInstanceSetting ignores updateMask and replaces its entire setting payload. Attachment and relation replacement likewise require the complete desired set. After a write times out, inspect the resulting resource before retrying. REST uses numeric error codes in its JSON status, while Connect has a separate wire representation.

Create and keep a personal token

In the application, open Settings → Access Tokens and select Create. Give the token a purpose-specific description and choose an expiry appropriate for the integration. Save the token immediately in your approved secret store; the creation result is the one-time token disclosure. Keep a separate token per integration so revoking one does not require replacing every client. This grants your account’s API access; it is not a promise of per-tool or read-only scopes.

Prepare a temporary Bash session

The example below prompts without echoing the token and does not put its literal value in shell history. Use your actual application origin with no trailing slash. Do not run with shell tracing or paste the resulting environment into a support report. It is a local example, not a replacement for a production secret manager. Run the read-only requests earlier on this page after setting these values; unset the token when finished.

export MEMOS_URL='https://notes.example.com'
read -r -s -p 'Personal access token: ' MEMOS_TOKEN
printf '\n'
export MEMOS_TOKEN
# Run the read-only checks above, then:
# unset MEMOS_TOKEN

Interpret a first response

GetCurrentUser should identify the account you intended to use. ListMemos returns a memos array and may include nextPageToken. An empty array is not an authentication failure by itself: the account may have no visible notes or your filters may exclude them. For 401, verify the Bearer header and token expiry/revocation. For 403, verify account/resource permissions. For 404, check the application origin and exact resource name before assuming a record is absent. Never send a token to the public documentation host to diagnose an application failure.