# Marfa ## Docs - [Force a one-shot run of the pending-delete purger](https://docs.myme.so/api-reference/admin/force-a-one-shot-run-of-the-pending-delete-purger.md): T-124 — Calls `PendingDeletePurger.runOnce()` directly and returns the count of accounts purged. Useful when an account has just passed its grace window and the operator doesn't want to wait for the next scheduled sweep (default cadence: 1 hour). Idempotent: re-running with no eligible rows returns… - [Get server metrics](https://docs.myme.so/api-reference/admin/get-server-metrics.md) - [Get tenant metrics](https://docs.myme.so/api-reference/admin/get-tenant-metrics.md): Per-tenant usage snapshot — item count by state, blob count and total bytes, custom-type count, and the most recent `system.activity` entries for the tenant. Platform-admin only. - [List a tenant's API keys](https://docs.myme.so/api-reference/admin/list-a-tenants-api-keys.md): Lists active (non-revoked) API keys for the named tenant. Operator surface for emergency revocation — pair with `DELETE /keys/:id`. Platform-admin only. - [List audit log entries](https://docs.myme.so/api-reference/admin/list-audit-log-entries.md): Returns audit-log entries in reverse-chronological order, optionally filtered by `action`, `resource_type`, `resource_id`, or a `since` / `until` time range. Cursor-paginated. Each entry carries the credential that performed the action (`key_id`), the resolved client IP (subject to `TRUSTED_PROXY_CI… - [List tenants](https://docs.myme.so/api-reference/admin/list-tenants.md): Lists every tenant in the instance with current operator-status. Platform-admin only. - [Restore items and blobs from an archive](https://docs.myme.so/api-reference/admin/restore-items-and-blobs-from-an-archive.md) - [Show a tenant](https://docs.myme.so/api-reference/admin/show-a-tenant.md): Returns the tenant row plus its current per-tenant quota overrides (null when no override is configured) plus a slice of recent `system.activity` items for the tenant. Platform-admin only. - [Suspend a tenant](https://docs.myme.so/api-reference/admin/suspend-a-tenant.md): Flips the tenant's `status` to 'suspended'. Future non-GET requests from credentials in this tenant are rejected at the auth middleware with HTTP 403 `tenant_suspended`. Reads pass through; platform admins bypass. Idempotent: re-suspending a suspended tenant is a no-op. Emits a `tenant.suspend` audi… - [Unsuspend a tenant](https://docs.myme.so/api-reference/admin/unsuspend-a-tenant.md): Flips the tenant's `status` back to 'active'. Reverse of `suspend`. Idempotent. Emits a `tenant.unsuspend` audit row. - [Download blob binary](https://docs.myme.so/api-reference/blobs/download-blob-binary.md): Streams the bytes for a previously-uploaded blob, identified by its `sha256:` hash. Response is `application/octet-stream` with the raw bytes. Tenant-scoped — a hash uploaded in tenant A is not visible to tenant B; cross-tenant probes return 404. - [Get a presigned download URL for a blob](https://docs.myme.so/api-reference/blobs/get-a-presigned-download-url-for-a-blob.md): Returns a time-limited presigned URL pointing directly at the underlying S3-compatible object store. The `ttl` query parameter (seconds, default 3600) sets the URL's lifetime. Useful for serving images and other static assets without proxying them through the API server. - [Reconcile blob storage](https://docs.myme.so/api-reference/blobs/reconcile-blob-storage.md): Compares the blob storage backend against the database to find orphaned files (in storage but not DB) and missing files (in DB but not storage). Defaults to dry_run=true for safety. - [Remove unreferenced blobs](https://docs.myme.so/api-reference/blobs/remove-unreferenced-blobs.md): Removes blobs that no item references — including items in trash. Run periodically to reclaim storage after item deletion accumulates orphaned blobs. Set `dry_run=true` to preview what would be removed without writing. Admin-only. - [Upload a blob](https://docs.myme.so/api-reference/blobs/upload-a-blob.md): Uploads binary content and returns its `sha256:` content-addressed hash. Accepts `multipart/form-data` (typical for browser file inputs) or `application/octet-stream` (raw bytes for SDK / CLI uploads). - [Introspect a leased token](https://docs.myme.so/api-reference/connection-leased-tokens/introspect-a-leased-token.md): Introspects a lease token. Returns RFC 7662–shaped fields — `active`, `connection_id`, `capability`, `scope`, `exp`, `iat` — for an external service to verify the token is still valid before honouring a callback. Tokens that are revoked, expired, or unrecognised return `active: false` with no furthe… - [Issue a leased token](https://docs.myme.so/api-reference/connection-leased-tokens/issue-a-leased-token.md): Mints a short-TTL bearer token an external service can use to call back into Marfa directly, without holding the connection's full runtime credential. The capability must be declared on the connection's integration manifest with `oauth_requirements: leased`; capabilities not declared as leased rejec… - [List active leases for a connection](https://docs.myme.so/api-reference/connection-leased-tokens/list-active-leases-for-a-connection.md): Returns leases attached to the connection that are not revoked and have not expired. Lease tokens themselves are never returned in list responses — only the lease metadata (id, capability, scopes, TTL, granted-at, last-used-at). - [Revoke a leased token](https://docs.myme.so/api-reference/connection-leased-tokens/revoke-a-leased-token.md): Invalidates a lease before its TTL expires. The next presentation of the token at `POST /lease-tokens/validate` returns `active: false`. Idempotent — revoking an already-revoked lease returns 200. - [Install an integration](https://docs.myme.so/api-reference/connections/install-an-integration.md): Server-side sibling of the browser consent flow at `POST /integrations/:id/install`. Skips the HTML consent screen — admin-only — so operators and tooling can install connections non-interactively. Body carries `integration_id`, an optional `label`, an optional `credential_ref`, and an optional `con… - [Preview event dispatch envelopes](https://docs.myme.so/api-reference/connections/preview-event-dispatch-envelopes.md): Renders the wire envelopes the reactive-run bridge would POST to Cloudflare Queues for a given item-event, without invoking any handler or producing a queue message. Operator debugging surface. Returns one entry per subscribing connection in the caller's tenant — `would_dispatch: true` with the synt… - [Uninstall an integration connection](https://docs.myme.so/api-reference/connections/uninstall-an-integration-connection.md): Revokes the connection's runtime credentials, deletes any upstream OAuth tokens, revokes active leased tokens, disables inbound webhook subscriptions, transitions the system.connection to state `revoked`, and emits a system.activity row. Audit-logged. Idempotent at the artefact level (revoking an al… - [Create a static API-token credential](https://docs.myme.so/api-reference/credentials/create-a-static-api-token-credential.md): Creates a `system.credential` of `kind: api_token` carrying an upstream service's API base URL + the user-supplied bearer token (encrypted at rest). The resulting credential id is passed as `credential_ref` on subsequent `POST /connections/install` calls. - [Create an OAuth provider credential](https://docs.myme.so/api-reference/credentials/create-an-oauth-provider-credential.md): Creates a `system.credential` of `kind: oauth_token` carrying an upstream service's OAuth client config — authorize URL, token URL, client_id, encrypted client_secret, upstream API base URL, and optional default scope. The resulting credential id is passed as `credential_ref` on subsequent `POST /co… - [Bulk upsert edges](https://docs.myme.so/api-reference/edges/bulk-upsert-edges.md): Creates or upserts up to 5000 edges in one call. Sibling to `POST /items/bulk` for the graph half of tenant migrations — items created in an earlier bulk call exist on the server; a second pass through this endpoint wires them together without having to hold source and target in the same payload. - [Create an edge](https://docs.myme.so/api-reference/edges/create-an-edge.md): Creates a single typed edge from source to target. Edges are first-class — they carry their own id, properties, and audit trail; they are not embedded references on the item. Source and target must both exist in the caller's tenant. - [Delete an edge](https://docs.myme.so/api-reference/edges/delete-an-edge.md): Deletes a single edge by id. Dual-gated on the source item's type write permission and the edge type's write permission. Cascade behaviour on the connected items is determined by the edge type's `cascade_on_delete`: `cascade` deletes connected items, `orphan` leaves them in place, `block` rejects th… - [List edges](https://docs.myme.so/api-reference/edges/list-edges.md): Returns a paginated list of edges across the tenant, optionally filtered by edge type. Use for taxonomy-style traversals — every reply, every annotation, every parent-of edge — without having to walk items first. Pass `edge_type` as a comma-separated list (up to 10 entries) to scope; omit to list ev… - [List inbound edges to an item](https://docs.myme.so/api-reference/edges/list-inbound-edges-to-an-item.md): Returns the edges where this item is the **target** (backrefs), paginated and optionally filtered by edge type. Use to walk an item's relationships inward — what notes are about this entity, what items are in this thread. For the forward direction, use `GET /items/{id}/edges`. - [List outbound edges from an item](https://docs.myme.so/api-reference/edges/list-outbound-edges-from-an-item.md): Returns the edges where this item is the **source**, paginated and optionally filtered by edge type. Use to walk an item's relationships outward — what does this note reference, what does this entity author. For the reverse direction (edges pointing AT this item), use `GET /items/{id}/backrefs`. - [Update an edge](https://docs.myme.so/api-reference/edges/update-an-edge.md): Updates the `properties` JSON on an edge. Identity fields — `edge_type`, `source_id`, `target_id` — are immutable after creation; attempts to change them return `400 validation_error`. To re-point an edge to a different target, delete the existing edge and create a new one. - [Delete an edge type](https://docs.myme.so/api-reference/edgetypes/delete-an-edge-type.md): Removes a custom edge type registration. Core edge types are immutable and rejected with 400. If existing edges of this type remain, the request fails — delete or migrate them first. Admin-only. - [List edge types](https://docs.myme.so/api-reference/edgetypes/list-edge-types.md): Returns every edge type registered in the tenant — the eight core types (`about`, `parent-of`, `in-thread`, `attached-to`, `references`, `authored-by`, `derived-from`, `supersedes`) plus any custom types registered via `POST /edges/types`. Each entry carries its cardinality, cascade behaviour, and s… - [Register an edge type](https://docs.myme.so/api-reference/edgetypes/register-an-edge-type.md): Registers a custom edge type. Carries `cardinality` (`one-to-one` / `one-to-many` / `many-to-one` / `many-to-many`), `cascade_on_delete` (`cascade` / `orphan` / `block`), source and target type constraints, and an optional `property_schema`. Core edge type names (`about`, `parent-of`, `in-thread`, `… - [Export tenant data](https://docs.myme.so/api-reference/export/export-tenant-data.md): Streams the tenant's items, edges, metadata, extensions, and blob references as NDJSON or a tar.gz archive. Filterable by `type`, `state`, `source`, `since` / `until`. NDJSON is the default — one JSON object per line, items first then edges then metadata, suitable for piping into another store or `j… - [Delete an extension namespace](https://docs.myme.so/api-reference/extensions/delete-an-extension-namespace.md): Removes one extension namespace from the item. Requires `write` on the namespace. Idempotent — deleting a namespace that doesn't exist returns 200 with the unchanged extensions response. - [Get an extension namespace](https://docs.myme.so/api-reference/extensions/get-an-extension-namespace.md): Returns the JSON payload for one extension namespace on the item. The caller must hold `read` (or `write`) on the namespace in `extension_permissions` — missing permission returns `403 forbidden` regardless of the caller's type access to the parent item. - [List extension namespaces for an item](https://docs.myme.so/api-reference/extensions/list-extension-namespaces-for-an-item.md): Returns every extension namespace attached to the item that the caller has permission to read. Extensions are namespaced JSON sidecars (`.*`, `.*`, `user.*`) — credentials must declare each namespace in their `extension_permissions` map; namespaces outside that map are silently filte… - [Replace an extension namespace](https://docs.myme.so/api-reference/extensions/replace-an-extension-namespace.md): Replaces the JSON payload for one extension namespace on the item. Body size is capped at 100KB — over-size payloads belong in a custom type with attachments or a `derived-from` edge, not in an extension. Requires `write` on the namespace in `extension_permissions`. Reserved namespaces (e.g. `connec… - [Deliver an inbound webhook](https://docs.myme.so/api-reference/inbound-webhooks/deliver-an-inbound-webhook.md): Public receipt endpoint that accepts a signed payload from an external service. The platform verifies the signature using the connection manifest's `webhook_verification.method` adapter, deduplicates against the sender's `external_delivery_id` (a unique index on `(subscription_id, external_delivery_… - [List inbound webhook subscriptions on a connection](https://docs.myme.so/api-reference/inbound-webhooks/list-inbound-webhook-subscriptions-on-a-connection.md): Returns every inbound-webhook subscription attached to the connection. Secrets are redacted in list responses — they only return at creation time. Use to render an operator surface showing what an integration is subscribed to upstream. - [List recent receipts for an inbound webhook subscription](https://docs.myme.so/api-reference/inbound-webhooks/list-recent-receipts-for-an-inbound-webhook-subscription.md): Returns recent inbound deliveries received on this subscription, newest first. Each entry records the sender's delivery id, the resolved adapter, the verification outcome (verified / unverified / dedup-hit), the dispatch outcome (ok / retry / failed), and any error reason. Use to debug a failing con… - [Register an inbound webhook subscription on a connection](https://docs.myme.so/api-reference/inbound-webhooks/register-an-inbound-webhook-subscription-on-a-connection.md): Registers an inbound-webhook subscription on an integration connection. External services (the connection's upstream) deliver events into Marfa by POSTing to the public receipt URL the platform exposes per subscription. Signature verification uses the adapter named in `webhook_verification.method` o… - [Replay an inbound webhook delivery](https://docs.myme.so/api-reference/inbound-webhooks/replay-an-inbound-webhook-delivery.md): Re-dispatches a previously-received inbound delivery from the DLQ. The original envelope is preserved verbatim — signature verification is not re-run (the receipt is already trusted), and the dedup window is bypassed (the operator is intentionally re-delivering). Use after deploying a connector-side… - [Get an integration](https://docs.myme.so/api-reference/integrations/get-an-integration.md): Returns one integration manifest by id. The full manifest body is included — triggers, OAuth requirements, webhook verification, target types, permissions, bidirectional handling. Use as the source-of-truth payload at install time so the consent screen renders the actual scopes the user is approving… - [List integrations](https://docs.myme.so/api-reference/integrations/list-integrations.md): Returns every registered integration manifest. Filter by `manifest_name` to enumerate versions of one integration. Each row carries the manifest contents, publisher metadata, and registration timestamps — use to render a marketplace surface or pick a version to install. - [Register an integration manifest](https://docs.myme.so/api-reference/integrations/register-an-integration-manifest.md): Registers an integration manifest as a `system.integration` item. One row per `(manifest_name, manifest_version)` pair; subsequent versions register as sibling items, not edits. The manifest is validated against `IntegrationManifestSchema` — declared triggers, OAuth requirements, webhook verificatio… - [Add tags to an item](https://docs.myme.so/api-reference/items/add-tags-to-an-item.md): Adds one or more tags to the item. Idempotent — tags already present are not duplicated. Tag strings should be kebab-case; reserved prefixes (`collection:`, `folder:`, `status:`, `priority:`) carry cross-app conventions. See [Metadata — tags](/concepts/metadata#tags). - [Apply a bulk action](https://docs.myme.so/api-reference/items/apply-a-bulk-action.md): Applies one action to every item matching a filter. Use to archive everything tagged `wip`, purge every trashed item older than 90 days, retier a slice of items, retag a source's items in bulk. - [Bulk upsert items](https://docs.myme.so/api-reference/items/bulk-upsert-items.md): Creates or upserts up to 5000 items in one call. Use for tenant migrations, importer runs, replays of an external source. Replaces the historical `/import` endpoint. - [Cancel a bulk-action job](https://docs.myme.so/api-reference/items/cancel-a-bulk-action-job.md): Signal cancellation. Queued jobs flip to `cancelled` immediately; in-progress jobs flip when the worker observes the flag between chunks (typically within seconds). Terminal jobs return their existing final state — no error. Auth: the originating credential or an admin. - [Create an item](https://docs.myme.so/api-reference/items/create-an-item.md): Creates an item against its type schema and persists it. The server stamps `id`, `created_at`, `version`, and `source` (from the caller's credential — not forgeable). Type-schema validation runs before any write. - [Get a bulk-action job](https://docs.myme.so/api-reference/items/get-a-bulk-action-job.md): Returns the current state of an asynchronous bulk_action job. Status progresses queued → in_progress → one of (completed | failed | cancelled). Once terminal, the `result` field carries the BulkActionResult envelope (matching the historic synchronous response). Only the credential that created the j… - [Get an item](https://docs.myme.so/api-reference/items/get-an-item.md): Returns a single item with its metadata layer flattened onto the object (`tags`, `tier`, `state`) and outbound edges hydrated inline, grouped by edge type. Extensions are NOT included — fetch them through the `/items/{id}/extensions` endpoints. - [Get item counts by state](https://docs.myme.so/api-reference/items/get-item-counts-by-state.md): Returns a count of items per lifecycle `state` (`active`, `archived`, `trashed`) for the tenant. Useful for surfacing item totals in a dashboard or sidebar without paging through `/items`. Type-permission scoped: a credential sees only the counts for types it can read. See [Lifecycle](/concepts/life… - [Get item metadata](https://docs.myme.so/api-reference/items/get-item-metadata.md): Returns the metadata layer for one item — `tags`, `tier`, `state`. Use when you have the item id and need the metadata fields without fetching the full item. For bulk reads, prefer `GET /items?include=metadata` to hydrate metadata inline across a page. See [Metadata](/concepts/metadata). - [List item versions](https://docs.myme.so/api-reference/items/list-item-versions.md): Returns the version-snapshot history for one item, newest first. Each snapshot carries the version number, the timestamp of the update that produced it, the full properties at that version, and the credential that wrote it. - [List items](https://docs.myme.so/api-reference/items/list-items.md): Returns a paginated list of items in the tenant, narrowed by the supplied query parameters. `type` matches subtypes via inheritance — `type=core.media` returns `core.media.book`, `core.media.article`, etc. `since` / `until` operate on the item's effective time (`timestamp`, falling back to `created_… - [Merge item metadata](https://docs.myme.so/api-reference/items/merge-item-metadata.md): Set-union-merges the supplied tags into the existing tag set. Existing tags survive; duplicates are deduped. Use this when an integration knows the tags it wants to add but doesn't want to clobber tags another source has already attached. For full replacement, use `PUT /items/{id}/metadata`. For inc… - [Permanently delete an item](https://docs.myme.so/api-reference/items/permanently-delete-an-item.md): Hard-deletes the item — irreversible. Removes the item row, all edges with this item as source or target, the metadata row, every extension scoped to this item, and attachment references. Blob bytes themselves are content-addressed and may be retained if referenced by other items. Admin-only; the no… - [Remove a tag from an item](https://docs.myme.so/api-reference/items/remove-a-tag-from-an-item.md): Removes one tag from the item. Idempotent — removing a tag the item doesn't carry returns 200 with the unchanged metadata. To bulk-remove tags or replace the full tag set, use `PUT /items/{id}/metadata` instead. - [Replace item metadata tags](https://docs.myme.so/api-reference/items/replace-item-metadata-tags.md): Replaces the item's tag set with the supplied array. An empty array clears all tags. The other metadata-layer fields (`tier`, `state`) are not affected — flip those through `PATCH /items/{id}` (for `tier`) or the lifecycle endpoints (for `state`). - [Restore a trashed item](https://docs.myme.so/api-reference/items/restore-a-trashed-item.md): Restores a `trashed` item to `active`. Sugar for the common case; the universal entry point is `POST /items/{id}/transition` with `state: active`. Trashed items are auto-purged after `TRASH_RETENTION_DAYS` (default 60) — restore before that window to keep the row. See [Lifecycle](/concepts/lifecycle… - [Soft delete an item](https://docs.myme.so/api-reference/items/soft-delete-an-item.md): Transitions the item to `state: trashed`. Reversible via `POST /items/{id}/restore` until the trash retention window expires (`TRASH_RETENTION_DAYS`, default 60 days; configurable per tenant via `TenantConfig.trash_retention_days`). After the window, the trash purger removes the row permanently. - [Transition item state](https://docs.myme.so/api-reference/items/transition-item-state.md): Transitions the item to the supplied `state`. Valid transitions: `active ↔ archived`, `active → trashed`, `archived → trashed`, `trashed → active` (restore). Direct `trashed → archived` is rejected with `400 invalid_transition` — restore to active first. Universal entry point used by the dedicated `… - [Update an item](https://docs.myme.so/api-reference/items/update-an-item.md): Updates an item's properties, tier, timestamp, or natural-key `source_id`. Properties shallow-merge into the existing row (unmentioned keys keep their values). The optional `version` field enables optimistic concurrency — pass the version the caller is editing from; a mismatch returns `409 version_c… - [Create an API key](https://docs.myme.so/api-reference/keys/create-an-api-key.md): Creates a new API key in the caller's tenant. The plaintext `key` field is returned **once** in the response — the server never shows it again. Store it securely; rotating means revoking the old key and creating a new one. - [List API keys](https://docs.myme.so/api-reference/keys/list-api-keys.md): Returns every API key in the caller's tenant. Hashes are returned in lieu of plaintext — the plaintext is only ever returned at creation time. `last_used_at` is debounced to at most one write per hour per key; treat it as a coarse activity signal, not an audit log. Admin or tenant_admin only. - [Revoke an API key](https://docs.myme.so/api-reference/keys/revoke-an-api-key.md): Revokes the key immediately. The next request bearing the revoked token returns `401 unauthorized`. In-flight long-lived connections (SSE) terminate on the next heartbeat. The revocation is audit-logged. Admin or tenant_admin only. - [Update an API key](https://docs.myme.so/api-reference/keys/update-an-api-key.md): Updates mutable fields on an API key in place — `label`, `default_tier`, and the four permission maps (`type_permissions`, `extension_permissions`, `edge_permissions`, `metadata_permissions`). `source` and `role` are immutable after creation and rejected with `400 validation_error` if present in the… - [List distinct tags in use](https://docs.myme.so/api-reference/metadata/list-distinct-tags-in-use.md): Returns every distinct tag in use across items the caller can read, with a usage count per tag, sorted by count descending then tag ascending. Tenant-scoped, type-permission scoped, excludes trashed items. Use to populate tag pickers, autocomplete, or `all tags` UI without iterating items. See [Meta… - [Delete the avatar](https://docs.myme.so/api-reference/profile/delete-the-avatar.md): Clears the uploaded avatar. The next read of the profile resolves `avatar_url` to a deterministic placeholder generated from `username`. Idempotent — clearing when no avatar is set returns the unchanged profile. - [Get the calling user's profile](https://docs.myme.so/api-reference/profile/get-the-calling-users-profile.md): Returns the profile for the user who owns the caller's tenant — `username`, `first_name`, `last_name`, `bio`, `avatar_url`, plus `email` (mirrored read-only from the auth identity record). - [Update the calling user's profile](https://docs.myme.so/api-reference/profile/update-the-calling-users-profile.md): Updates any subset of `username`, `first_name`, `last_name`, `bio`. Username changes flow through the same validators as handle claims (reserved-handle and uniqueness checks). Username collisions return `409 conflict`; reserved values return `400 handle_reserved`. Email is read-only from the auth id… - [Upload an avatar](https://docs.myme.so/api-reference/profile/upload-an-avatar.md): Uploads an image as the user's avatar. The accepted MIME types are enumerated on the request body schema. Subject to the standard blob size cap and the tenant's `blobs` and `storage_bytes` quotas — over-size returns `413`. The uploaded image is stored as a content-addressed blob; the public `avatar_… - [Search items](https://docs.myme.so/api-reference/search/search-items.md): Full-text search across the tenant's items. Indexes textual properties (body, title, description, name, and other string-typed fields not flagged `searchable: false`) plus tags. Ranking is by relevance with a configurable recency boost. - [Get DLQ context for a connection](https://docs.myme.so/api-reference/system/get-dlq-context-for-a-connection.md): Returns minimal connection metadata for the runtime-control DLQ peek/replay routes. Operator-debug surface. Unlike verify-context, this does NOT narrow by kind or state — operators inspect DLQs precisely when a connection is unhealthy. - [Get verify context for a connection](https://docs.myme.so/api-reference/system/get-verify-context-for-a-connection.md): Returns the manifest `integration_name` and `tenant_id` the runtime-control verify route needs to construct a queue envelope. Validates the connection exists, is `kind: integration`, and is active. Operator-debug surface. - [Issue a runtime credential](https://docs.myme.so/api-reference/system/issue-a-runtime-credential.md): Mints a short-lived API key scoped to a single connection. The runtime-control plane calls this to provision the credential a per-integration Worker presents when invoking Marfa on the connection's behalf. The `api_key` field is returned **once**; subsequent reads omit it. - [List inbound webhook subscriptions](https://docs.myme.so/api-reference/system/list-inbound-webhook-subscriptions.md): Returns every inbound-webhook subscription attached to a connection, with decrypted secrets included so the runtime-control plane can verify inbound HMAC signatures. - [Get current tenant quotas](https://docs.myme.so/api-reference/tenants/get-current-tenant-quotas.md): Returns the calling tenant's quota ceilings, resolved from the calling credential's tenant so the caller doesn't need to know its own tenant id. Returns a row of nulls when no per-tenant override is configured (env defaults apply). Platform-admin keys with no tenant id receive `400` — use `GET /tena… - [Get tenant quotas](https://docs.myme.so/api-reference/tenants/get-tenant-quotas.md): Returns the per-tenant quota ceilings for a specific tenant — items, webhooks, blobs, storage bytes, and per-minute rate limit. `null` on a field means the env default applies; an entirely-null payload means no per-tenant override is configured. Platform-admin only — tenant admins use `GET /tenants/… - [Get the current tenant's configuration](https://docs.myme.so/api-reference/tenants/get-the-current-tenants-configuration.md): Returns the tenant-level configuration. Carries the three optional schema-enforcement levers under `enforcement` (`strict_mode`, `source_allowlist`, `source_filter` — see [Schema enforcement](/concepts/schema-enforcement)) plus the per-tenant cleanup-job overrides (`audit_retention_days`, `event_log… - [Replace the current tenant's configuration](https://docs.myme.so/api-reference/tenants/replace-the-current-tenants-configuration.md): Overwrites the tenant's config with the supplied object — full replacement, not merge. The accepted shape carries the optional `enforcement` block (`strict_mode`, `source_allowlist`, `source_filter`) plus the per-tenant cleanup-job overrides (`audit_retention_days`, `event_log_retention_hours`, `tra… - [Update tenant quotas](https://docs.myme.so/api-reference/tenants/update-tenant-quotas.md): Sets the per-tenant quota ceilings for a specific tenant. Each field is independent — supplied non-null values override the env default; supplied `null` resets to the env default for that field. Platform-admin only. - [Delete a custom type](https://docs.myme.so/api-reference/types/delete-a-custom-type.md): Removes a custom type registration. Admin-only — core types are immutable. By default, deletion is rejected if any item of the type still exists. Pass `?force=true` to delete the type and orphan existing rows (rows persist with the type identifier intact, but new writes against that type return `400… - [Get a type](https://docs.myme.so/api-reference/types/get-a-type.md): Returns the full schema for a single type — fields, parent, `display_hints`, `merge_policy`, `version_policy`. Resolves both core and tenant-registered custom types by identifier. - [List types](https://docs.myme.so/api-reference/types/list-types.md): Returns every type registered in the tenant — the core type catalogue plus any custom types registered via `POST /types`. Each entry carries the type identifier, parent (for inheriting types), fields, optional `display_hints`, `merge_policy`, and `version_policy`. Use as the manifest a custom-type-a… - [Register a custom type](https://docs.myme.so/api-reference/types/register-a-custom-type.md): Registers a custom type at runtime. Identifier must namespace under one of `app..`, `user.`, or `.` — reserved roots (`core`, `system`, `marfa`) reject with `400 reserved_namespace`. Bodies are validated; mismatched semver bumps (additive change submitted as ma… - [Update a custom type](https://docs.myme.so/api-reference/types/update-a-custom-type.md): Replaces a custom type's schema. Admin-only — core types are immutable and return 400. Re-runs the registration-time correctness rails (semver diff, inheritance check, field-name validation). The diff between the prior and new version sets the required version bump; mismatched bumps reject with `400… - [Create a webhook](https://docs.myme.so/api-reference/webhooks/create-a-webhook.md): Registers an outbound webhook subscription. Each subscription targets a URL and one or more event names (`item.created`, `item.updated`, `edge.created`, etc. — wildcards accepted). The optional `type_filter` narrows item events to specific item types. - [Delete a webhook](https://docs.myme.so/api-reference/webhooks/delete-a-webhook.md): Removes the subscription. In-flight deliveries already queued continue to fire and retry per the standard schedule; no new deliveries are queued. Delivery history rows are retained until the audit retention window expires. - [Get a webhook](https://docs.myme.so/api-reference/webhooks/get-a-webhook.md): Returns one outbound webhook subscription by id. Secret is redacted. To pair with delivery history, use `GET /webhooks/{id}/deliveries`. - [List webhook deliveries](https://docs.myme.so/api-reference/webhooks/list-webhook-deliveries.md): Returns recent delivery attempts for one subscription, newest first. Each entry carries the event id, the resolved URL, the response status, attempt count, and the next retry time (when retrying). Use to debug delivery failures and confirm that `X-Marfa-Event-Id` deduplication is working on the rece… - [List webhooks](https://docs.myme.so/api-reference/webhooks/list-webhooks.md): Returns every outbound webhook subscription in the caller's tenant. Secrets are redacted in every list response — the plaintext is only returned at create time. Use to render an operator surface for inspecting registered URLs, events, and filters. - [Update a webhook](https://docs.myme.so/api-reference/webhooks/update-a-webhook.md): Updates mutable fields on an outbound webhook subscription — `url`, `events`, `type_filter`, `active`. Body is a partial: unsupplied fields keep their existing values. To rotate the signing secret, delete the subscription and create a new one. - [Authentication](https://docs.myme.so/api/authentication.md): API keys and OAuth 2.1 — two ways credentials reach the server - [Bulk operations](https://docs.myme.so/api/bulk-operations.md): Two endpoints for moving data and mutating many items at once - [Errors](https://docs.myme.so/api/errors.md): Error response shape, codes, and how to handle them - [Inbound webhooks](https://docs.myme.so/api/inbound-webhooks.md): Public receipt endpoints for Integration connectors — verification, dedup, dispatch, and replay - [Logging and request IDs](https://docs.myme.so/api/logging.md): How Marfa surfaces observability — request IDs, structured log entries, and the conventions SDKs follow - [Permissions](https://docs.myme.so/api/permissions.md): Three permission maps — types, extensions, edges — and the dual-gate rule - [Rate limiting](https://docs.myme.so/api/rate-limiting.md): Per-credential request caps, response headers, and how clients should back off - [Realtime](https://docs.myme.so/api/realtime.md): Server-Sent Events for live updates, with reconnection via Last-Event-ID - [Search and query](https://docs.myme.so/api/search-and-query.md): Full-text search across a tenant, plus the filter language for item list and search queries - [Webhooks](https://docs.myme.so/api/webhooks.md): Durable outbound event delivery with HMAC signatures and retry - [Building a client](https://docs.myme.so/clients/building-a-client.md): Patterns for apps, CLIs, and integrations that consume a Marfa server - [CLI](https://docs.myme.so/clients/cli.md): @withmarfa/cli — the `my` command-line client for a Marfa server - [MCP server](https://docs.myme.so/clients/mcp.md): @withmarfa/mcp — Model Context Protocol server exposing the Marfa API to Claude and other MCP clients - [Clients](https://docs.myme.so/clients/overview.md): In-house clients and the pattern for building your own - [Sync agent](https://docs.myme.so/clients/sync.md): Mirror local folders into Marfa. Files on disk become typed items; edits round-trip both ways. - [Activity](https://docs.myme.so/concepts/activity.md): How operator-visible state surfaces — system.activity items and severity levels - [Audit log](https://docs.myme.so/concepts/audit.md): Append-only record of every write and administrative action - [Authoring types](https://docs.myme.so/concepts/authoring-types.md): The correctness rails for getting types right at registration — semver diff, the SDK helper, the inherit-vs-sibling rubric, error shapes - [Blobs](https://docs.myme.so/concepts/blobs.md): Content-addressed binary storage — SHA-256 references, deduplication, and tiered backends - [Conflicts](https://docs.myme.so/concepts/conflicts.md): How concurrent edits resolve — per-type merge policy, keep-both semantics, and the 409 envelope - [Connections](https://docs.myme.so/concepts/connections.md): How Marfa talks to apps, external services, and other spaces — the system.connection type and its three kinds - [Conventions](https://docs.myme.so/concepts/conventions.md): Style and structural rules for anyone extending Marfa with custom types, edges, or extensions - [Edges](https://docs.myme.so/concepts/edges.md): First-class typed relationships between items - [Extensions](https://docs.myme.so/concepts/extensions.md): Namespaced sidecar data attached to items - [Handles and publishers](https://docs.myme.so/concepts/handles-and-publishers.md): Publisher identity for accounts and community-published types — username convention, reservations, change policy, account deletion - [Integrations](https://docs.myme.so/concepts/integrations.md): Published manifests that connect Marfa to external services — runtime tiers, manifest contract, install flow - [Items](https://docs.myme.so/concepts/items.md): The primitive — typed records with system fields, properties, and a metadata layer - [Tier](https://docs.myme.so/concepts/library.md): The library / feed axis — the primary split between curated and high-volume items - [Lifecycle](https://docs.myme.so/concepts/lifecycle.md): Universal three-state model — active, archived, trashed - [Marketplace](https://docs.myme.so/concepts/marketplace.md): Where community schemas and integrations are published, discovered, and installed - [Metadata](https://docs.myme.so/concepts/metadata.md): Tags, tier, state — the universal layer applied to every item - [Namespaces](https://docs.myme.so/concepts/namespaces.md): The five-tier namespace model — reserved roots, app and publisher prefixes, sibling vs child types - [Profile](https://docs.myme.so/concepts/profile.md): The signed-in user's account profile — username, name, bio, avatar — served via /profile/me and the OIDC userinfo endpoint - [Provenance](https://docs.myme.so/concepts/provenance.md): Honest source — who wrote an item - [Runtime substrates](https://docs.myme.so/concepts/runtime-substrates.md): The two substrates that run integrations — Cloudflare (hosted) and Node + Postgres (local) — and where they differ semantically. - [Schema enforcement](https://docs.myme.so/concepts/schema-enforcement.md): Always-on validation plus three optional console-controlled levers - [Spaces](https://docs.myme.so/concepts/spaces.md): Spaces as the data boundary, credentials as space scope - [System types](https://docs.myme.so/concepts/system-types.md): Platform-internal operational items — devices, credentials, webhooks, app identities - [Types](https://docs.myme.so/concepts/types.md): The schema system — core types, custom types, inheritance, and the full core catalog - [Versions](https://docs.myme.so/concepts/versions.md): Per-item version history with time-aware thinning and a hard cap - [Introduction](https://docs.myme.so/introduction.md): What Marfa is and the problem it solves - [Authentication](https://docs.myme.so/sdks/swift/authentication.md): OAuth 2.1 with ASWebAuthenticationSession, Keychain helpers, token storage - [Data access](https://docs.myme.so/sdks/swift/data-access.md): Items, edges, metadata, extensions, blobs, search namespaces - [Errors and testing](https://docs.myme.so/sdks/swift/errors-and-testing.md): Conflict handling, errors, testing, concurrency model - [Overview](https://docs.myme.so/sdks/swift/overview.md): Install, three client modes, configuration - [Sync engine](https://docs.myme.so/sdks/swift/sync-engine.md): SwiftUI reactive queries, sync engine, sync events, end-to-end subscription, local IDs - [Typed models](https://docs.myme.so/sdks/swift/typed-models.md): Typed domain models and custom-type codegen - [TypeScript](https://docs.myme.so/sdks/typescript.md): @withmarfa/sdk — the TypeScript client for a Marfa server - [Using the SDK in Electron](https://docs.myme.so/sdks/typescript-electron.md): How to consume @withmarfa/sdk from an Electron main process - [Account lifecycle](https://docs.myme.so/self-hosting/account-lifecycle.md): Account deletion on hosted Marfa — request, email-confirm, 30-day grace window, permanent purge with audit redaction - [Configuration](https://docs.myme.so/self-hosting/configuration.md): Environment variables for running a Marfa server - [Conformance](https://docs.myme.so/self-hosting/conformance.md): A black-box test suite that validates any Marfa server implementation against the platform spec — for self-hosters and alternative implementations - [Deploying a server](https://docs.myme.so/self-hosting/deployment.md): Deploying and operating a self-hosted Marfa server - [Deployment modes](https://docs.myme.so/self-hosting/deployment-modes.md): Three ways Marfa can run — local-only, server-synced, third-party-synced - [Hosted mode](https://docs.myme.so/self-hosting/hosted-mode.md): Multi-tenant deployments with user signup and tenant provisioning - [Platform](https://docs.myme.so/self-hosting/platform.md): Platform-operator surface — list, inspect, suspend, set quotas, view metrics, list keys, force a pending-delete sweep — via the `my platform` CLI ## OpenAPI Specs - [openapi](https://docs.myme.so/openapi.json)