Rust · 0.1.0

API reference

The complete REST contract for this Rust distribution. 92 operations, 119 schemas, one current version.

Static reference only. This website never asks for tokens or sends API requests. Use your application origin, not this site, for integrations.

Start with API access for authentication, pagination and retries. Download the complete OpenAPI JSON.

Choose the application origin and credential

Send requests to your own application origin under /api/v1. A personal access token or session access token belongs in Authorization: Bearer … . The refresh cookie alone does not authenticate ordinary REST calls. A PAT acts as its account; it does not add permissions or bypass space membership. First verify the credential with GET /api/v1/auth/me. Never put real tokens in URLs, examples, screenshots or issue reports.

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

Resource names and URL segments

A resource name such as memos/example is different from its final identifier example. For GET /api/v1/memos/{memo}, substitute only example into {memo}; use the full memos/example when another JSON field asks for a memo resource name. User paths use usernames, not display names or database IDs. Space members and invitations use the target username as their final segment. URL-encode query values with a client library or curl --data-urlencode.

JSON bodies are operation-specific

Use the body schema shown on the operation page. CreateMemo and UpdateMemo accept a Memo object directly, not a {memo: …} wrapper; set-attachment and set-relation calls accept their named request objects. Path-bound names are supplied by the URL. JSON bytes fields contain base64, 64-bit counts and offsets use decimal strings, and timestamps use RFC 3339 strings. Read-only fields describe output; a shared resource schema's required list is not a command to resend every field during PATCH. The examples are checked against the contract and Rust binding code, not executed against a live instance.

Use explicit update masks

The updateMask query value is a comma-separated list of protobuf field paths, such as content,pinned or display_name. These paths can differ from lowerCamelCase JSON field names such as displayName. REST can infer a mask for certain PATCH bodies, but nested settings have operation-specific behavior, so use an explicit supported mask. In particular, UpdateInstanceSetting ignores updateMask and replaces the entire selected setting payload; read its warning before changing configuration.

Page through the response you receive

Where pagination is implemented, reuse nextPageToken unchanged with the same filter, state and ordering until the token is empty. Treat tokens as opaque: ListAttachments uses a different cursor representation from most other lists. Defaults are generally 50 with a maximum of 1000, but some small collections intentionally return everything despite declaring pageSize/pageToken. Their operation notes identify the exceptions. Collection results are authorization-filtered; an empty list does not prove that an object does not exist.

Interpret errors before retrying

REST failures return an HTTP status and a JSON Status object with numeric gRPC code, message and details. Connect uses its own wire error representation, so do not parse the two transports identically. Invalid input, missing credentials, denied access, unavailable resources and failed preconditions need different fixes. NOT_FOUND may deliberately conceal an inaccessible or archived resource. Rate-limit failures can include Retry-After, RateLimit, RateLimit-Policy and structured RetryInfo; respect them. A lost response or a storage-cleanup error after a write can leave the database change committed. Read back state before repeating a creation, deletion or replacement.

Empty results and file downloads

No declared request body means there is no JSON payload to build. For commands returning protobuf Empty, the Rust REST transport returns HTTP 200 with JSON {}; the OpenAPI snapshot omits a response schema for those commands. ExportMemos is different: its successful response is raw ZIP bytes with the server's Content-Type, not JSON or a base64 wrapper. Save that response as a file and still inspect non-success responses as errors.