Available endpoints

Use this catalog for Memex request shapes. Agents should fetch this page before the first Memex request in a new session and again whenever a request fails because of an unknown field, tool name, or argument shape.

Surface map

Use case	REST	MCP	Skill or plugin
Search saved content	`POST /search`	`search_content`	Defaults to the compact response shape. Use `raw=true` for the rich machine-readable payload. `POST /search-content` is also accepted.
Save content or a public URL	`POST /save-content-entity`	`save_content_by_url`	Use `save-content-entity` for structured saves. Use `POST /save-content-by-url` for URL-only saves.
Create a saved view	`POST /create-view`	-	Creates a reusable saved search scope for the authenticated user.
List accessible saved views	`POST /list-views`	-	Returns owned views plus views shared with the authenticated user.
Search inside a saved view	`POST /execute-view-search`	-	Runs the raw search response shape constrained to a view ID or public view token.
Create a public sharing link	`POST /ensure-shared-library-entry-link`	`create_sharing_link`	Creates or updates a share link for saved content with view or collaborate access.
List public sharing links	`POST /list-shared-library-entry-links`	`list_sharing_links`	Lists existing content share links and their view or collaborate access.
List subscribed feeds	`POST /list-feeds`	`list_subscribed_feeds`	Returns the authenticated user’s subscribed RSS and YouTube feeds.
List handoffs	`POST /list-handoffs`	`list_handoffs`	Returns handoffs across every status and approval state by default, with optional reference, status, readiness, and time-frame filters.
Drain handoff	`POST /drain-handoff`	`drain_handoff`	Marks a pulled handoff as processed via API pull.
Create an account for a human	`POST /agent-create-user`	-	Used by agent signup flows
Fetch current plans	`POST /get-available-plans`	-	Used by credit purchase flows
Fetch all available tag names	`POST /get-available-tag-names`	`execute_action`	Use action ID `tags.search` with empty input to return the authenticated user’s current tags.
List auto-tagging rules	`POST /list-auto-tagging-rules`	-	Returns the authenticated user’s auto-tagging rules
Create an auto-tagging rule	`POST /create-auto-tagging-rule`	-	Creates an auto-tagging rule for existing tag IDs
Complete checkout for an authenticated user	`POST /checkout`	-	Buys one-time credit plans with a Stripe Shared Payment Token

Preferred base URL: https://memex.garden/api

Core operations

Search saved content

REST route: POST https://memex.garden/api/search
Also accepted: POST https://memex.garden/api/search-content
MCP tool: search_content
Auth: Authentication
Response contract: Response shape

Parameters

Field	Type	Required	Notes
`query`	`string`	No	Search text. Can include inline tags like `#tag-name`.
`rewriteQuery`	`boolean`	No	Rewrites the query before embedding generation.
`forceFullQueryProcessing`	`boolean`	No	Forces full query processing even for short queries.
`includeFields`	`string[]`	No	Optional allow-list of fields to return on result entities.
`excludeFields`	`string[]`	No	Optional block-list of result fields.
`tag`	`string`	No	Tag filter string. Space- or comma-separated values are accepted.
`tag_ids`	`string[]`	No	Explicit tag IDs to filter on.
`tagMatchStrategy`	`"AND" \| "OR"`	No	Default is `"AND"`.
`dateFrom`	`string`	No	Inclusive lower date bound.
`dateTo`	`string`	No	Inclusive upper date bound.
`timeRange`	`{ start?: number; end?: number }`	No	Explicit timestamp range in milliseconds.
`contentTypes`	`string[]`	No	Exact `content_entity.type` filter list. Pass one or more values to restrict search results to those stored content types.
`feedIds`	`string[]`	No	Restricts search to entries from one or more subscribed feed IDs. Get IDs from `POST /list-feeds` or MCP `list_subscribed_feeds`.
`feedScope`	`"all"`	No	Set to `"all"` to restrict search to entries from all subscribed feeds. Omit to search the full library unless `feedIds` is set.
`feedReadStates`	`("unread" \| "read" \|"pending" \| "processing" \| "processed" \| "failed" \| "archived")[]`	No	Optional read-state filter for feed entries. Omit to include unread and read entries while excluding archived entries.
`viewIds`	`string[]`	No	Restricts search to one or more accessible saved views. Use this for view-scoped searches that need LLM-ready or full responses.
`sortBy`	`"date-asc" \| "date-desc"`	No	Default is `"date-desc"`.
`offset`	`number`	No	Minimum `0`. Default is `0`.
`limit`	`number`	No	Minimum `1`, maximum `500`, default `30`.
`relevanceThreshold`	`number`	No	Semantic relevance threshold.
`enableRerank`	`boolean`	No	Overrides reranking behavior. Default is on for compact `raw=false` output and off for `raw=true`.
`raw`	`boolean`	No	Default `false`. `false` returns the compact slim response as a `results` array. `true` returns the full machine-readable payload.
`rerankWindow`	`number`	No	Default `100`, capped at `100`.
`includeTags`	`boolean`	No	Includes related tags in the reference payload.
`includeNotes`	`boolean`	No	Includes annotations attached to each matched content entity. Default is `false`.

Search behavior

raw defaults to false, which returns the compact, token-efficient response shape with consistent top-level type, url, createdAt, title?, text, and optional slim media.
Set raw: true to receive the original machine-readable response with results, extraEntities, referencesByResultId, referencedEntities, and referencedTags.
If your client exposes response options named llm and full, use llm when you want the default compact response (raw: false or omitted), and use full when you want the machine-readable response (raw: true).
Search responses include direct references for annotation and chat-thread results by default.
Search result entities include a resolved url whenever Memex can derive a stable source URL. Prefer that field for citations and references.
includeTags adds related tag entities and tag IDs to referencesByResultId.
In raw: true, includeNotes adds an annotations array on each matched result. Each note includes compiled text, resolvedReferences, and a references field. That references field contains the note’s direct reference entities, and if one of those direct references is itself an annotation, that nested annotation includes its own references one level deeper.
In raw: false, includeNotes adds user_notes on each compact result in the results array. Each note is precompiled into YAML text with its own compact references object.
Raw annotation and chat-thread references are resolved from both reference_content_ids and memex-reference nodes found inside annotation JSON content or chat-thread message JSON content.
Search responses report charges directly in USD micros through usageMicrosCharged and the remaining dollar-denominated balance through remainingUsageBalance.
Compact raw=false requests default reranking on when the query is eligible for rerank. Raw raw=true requests default reranking off unless you explicitly pass enableRerank: true.
Search requests currently report usageMicrosCharged: 0.
Unsupported contentTypes values are rejected with an error that includes the supported values.
Omitting both feedIds and feedScope searches the full library, not only feed-sourced content.

LLM vs full response options

Use the same search route for both response modes:

llm response: omit raw or set "raw": false. This is the default and is best for agent prompts, summaries, and direct LLM context because results are compact and normalized.
full response: set "raw": true. This is best for programmatic processing because it preserves the full result graph, including extraEntities, referencesByResultId, referencedEntities, and referencedTags.

Search inside a view with the LLM-ready response:

{
    "viewIds": ["view_id"],
    "query": "vector database benchmarks",
    "limit": 10,
    "raw": false
}

Search inside a view with the full response:

{
    "viewIds": ["view_id"],
    "query": "vector database benchmarks",
    "limit": 10,
    "raw": true,
    "includeNotes": true
}

Feed-focused search

Use POST /list-feeds or MCP list_subscribed_feeds to fetch feed IDs first. Search one feed:

{
    "query": "vector databases",
    "feedIds": ["feed_id"],
    "limit": 20
}

Search multiple specific feeds:

{
    "query": "vector databases",
    "feedIds": ["feed_id_1", "feed_id_2"],
    "limit": 20
}

Search all subscribed feeds:

{
    "query": "vector databases",
    "feedScope": "all",
    "limit": 20
}

Include archived feed entries as well:

{
    "query": "vector databases",
    "feedScope": "all",
    "feedReadStates": ["unread", "read","pending" \| "processing" \| "processed" \| "failed" \| "archived"],
    "limit": 20
}

Available `contentTypes` values

These are the exact persisted content_entity.type values accepted by POST /search, POST /search-content, and the MCP search_content tool: web, pdf, youtube, twitter, instagram, tiktok, facebook, linkedin, pinterest, reddit, chatgpt, claude, annotation, image, transcribedMedia, audioRecording, selector, chatThread, twitterProfile, subreddit, youtubeChannel Example:

{
    "query": "transcript search",
    "contentTypes": ["youtube", "transcribedMedia", "audioRecording"],
    "limit": 10
}

Save content or a public URL

REST route: POST https://memex.garden/api/save-content-entity
URL-only REST route: POST https://memex.garden/api/save-content-by-url
MCP tool: save_content_by_url
Auth: Authentication
Response contract: Response shape

Parameters

URL-save payload:

{
    "data": {
        "url": "https://example.com/article",
        "title": "Optional title",
        "description": "Optional description",
        "html": "<main>Optional HTML</main>"
    },
    "tags": ["research"],
    "includeHtml": false
}

URL-only payload:

Field	Type	Required	Notes
`url`	`string`	Yes	Public URL to save.
`tags`	`string[]`	No	Tag names. Missing tags are created and attached.
`title`	`string`	No	Optional title override.
`description`	`string`	No	Optional description override.
`html`	`string`	No	Optional HTML payload for web saves.
`includeHtml`	`boolean`	No	If `true`, the response includes HTML on web entities.

Behavior notes:

Tag names are trimmed and deduplicated.
For normal web URLs without html, Memex fetches the page body itself.
Pass data.url for structured saves, or url for URL-only saves.

REST route: POST https://memex.garden/api/ensure-shared-library-entry-link
MCP tool: create_sharing_link
Auth: Authentication
Response contract: Response shape

MCP payload:

Field	Type	Required	Notes
`contentId`	`string`	Yes	Saved content entity ID returned by `search_content`, `save_content_by_url`, or REST saves.
`access`	`"view" \| "collaborate"`	No	Default is `"view"`. `"collaborate"` creates or updates the link with collaborative access.

REST payload:

Field	Type	Required	Notes
`contentId`	`string`	Yes	Saved content entity ID to share.
`accessMode`	`"public_link" \| "public_link_contribute"`	Yes	Use `"public_link"` for view access and `"public_link_contribute"` for collaborative access.

MCP example:

{
    "contentId": "content_entity_id",
    "access": "collaborate"
}

MCP response includes:

shareUrl: full Memex URL for the public share link
publicToken: underlying public invite token
access: requested API access value, either view or collaborate
accessMode: stored Memex access mode

REST route: POST https://memex.garden/api/list-shared-library-entry-links
MCP tool: list_sharing_links
Auth: Authentication
Response contract: Response shape

MCP payload:

Field	Type	Required	Notes
`contentId`	`string`	No	Optional saved content entity ID to filter by.
`contentType`	`string`	No	Optional exact `content_entity.type` value to filter by.
`access`	`"view" \| "collaborate"`	No	Optional access filter. Omit to return both view and collaborate links.

REST payload:

Field	Type	Required	Notes
`contentId`	`string`	No	Optional saved content entity ID to filter by.
`contentType`	`string`	No	Optional exact `content_entity.type` value to filter by.
`accessMode`	`"public_link" \| "public_link_contribute"`	No	Optional access-mode filter. Omit to return both view and collaborate links.

MCP example:

{
    "access": "collaborate"
}

MCP response:

{
    "links": [
        {
            "sharedResourceId": "shared_resource_id",
            "contentId": "content_entity_id",
            "contentType": "web",
            "access": "view",
            "accessMode": "public_link",
            "publicToken": "public_token",
            "shareUrl": "https://memex.garden/read/content_entity_id?invite=public_token",
            "createdAt": "2026-06-14T00:00:00.000Z"
        }
    ]
}

View endpoints

Views are saved search scopes. Use them to define a reusable subset of a Memex library, list the caller’s accessible scopes, then run search constrained to one view.

`POST /create-view`

Full URL: https://memex.garden/api/create-view
Auth: authenticated user
Used for: creating a saved view owned by the caller

Field	Type	Required	Notes
`title`	`string`	Yes	View title. Empty titles are rejected.
`description`	`string`	No	Optional description.
`favicon`	`string`	No	Optional icon URL or emoji-like display value.
`scope`	`ViewScopeV1`	Yes	Saved scope expression. `version` must be `1`.

scope.expression can be one of:

Type	Shape
`library`	`{ "type": "library" }`
`query`	`{ "type": "query", "text": "vector databases" }`
`tag`	`{ "type": "tag", "tagId": "tag_id" }`
`contentType`	`{ "type": "contentType", "contentType": "web" }`
`time`	`{ "type": "time", "field": "contentCreatedAt", "start": 1717200000000, "end": 1719792000000 }`
`feed`	`{ "type": "feed", "feedId": "feed_id", "entryScope": "saved" }`
`group`	`{ "type": "group", "operator": "AND", "children": [ ...expressions ] }`
`not`	`{ "type": "not", "child": { ...expression } }`

Example:

curl https://memex.garden/api/create-view \
  -H "X-Api-Key: YOUR_MEMEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI research",
    "description": "Saved web and PDF sources tagged for AI research",
    "scope": {
      "version": 1,
      "expression": {
        "type": "group",
        "operator": "AND",
        "children": [
          { "type": "tag", "tagId": "tag_ai_research" },
          { "type": "contentType", "contentType": "web" }
        ]
      },
      "defaults": {
        "sortBy": "date-desc",
        "includeNotes": true
      }
    }
  }'

Response notes:

Returns view.
view.id is the value to pass as viewId to /execute-view-search.
defaults.sortBy applies when a view search request omits sortBy.
defaults.includeNotes controls whether scoped search returns attached notes.

`POST /list-views`

Full URL: https://memex.garden/api/list-views
Auth: authenticated user
Used for: listing views the caller owns or can access through sharing

Request body:

{}

Response notes:

Returns views: ViewListItem[].
Each view includes id, title, description, scope, createdAt, updatedAt, and accessRole.
accessRole is owner, viewer, or writer.
Returns tagEntities for tag IDs referenced by the listed view scopes.

`POST /execute-view-search`

Full URL: https://memex.garden/api/execute-view-search
Auth: authenticated user for viewId, or no auth when using a public shared view token
Used for: searching only inside the content matched by a saved view
Response contract: the full/raw /search response shape from Response shape

POST /execute-view-search always returns the full response shape. If you want the LLM-ready compact response for a private view, call POST /search with viewIds: ["view_id"] and omit raw or set raw: false. Use raw: true for the full response.

Field	Type	Required	Notes
`viewId`	`string`	Required unless `token` is supplied	Saved view ID accessible to the authenticated user.
`token`	`string`	Required unless `viewId` is supplied	Public shared view token.
`query`	`string`	No	Search text inside the view. Omit it to browse the view by sort order.
`rewriteQuery`	`boolean`	No	Rewrites the query before embedding generation.
`forceFullQueryProcessing`	`boolean`	No	Forces full query processing even for short queries.
`enableRerank`	`boolean`	No	Enables LLM reranking when the query is eligible.
`rerankWindow`	`number`	No	Candidate window for reranking. Maximum `100`.
`includeChunkContext`	`boolean`	No	Includes nearby chunk context in eligible raw results.
`tagIds`	`string[]`	No	Additional tag filter. Each tag ID must already belong to the view scope.
`contentTypes`	`string[]`	No	Further restricts results to exact `content_entity.type` values.
`timeRange`	`{ start?: number; end?: number }`	No	Further restricts results by Unix timestamps in milliseconds.
`sortBy`	`"date-asc" \| "date-desc"`	No	Overrides the view default sort.
`offset`	`number`	No	Minimum `0`. Default is `0`.
`limit`	`number`	No	Minimum `1`, maximum `500`, default `30`.

Authenticated view example:

curl https://memex.garden/api/execute-view-search \
  -H "X-Api-Key: YOUR_MEMEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "viewId": "view_id",
    "query": "vector database benchmarks",
    "limit": 10,
    "enableRerank": true
  }'

Public token example:

curl https://memex.garden/api/execute-view-search \
  -H "Content-Type: application/json" \
  -d '{
    "token": "public_view_token",
    "query": "launch notes",
    "limit": 10
  }'

Behavior notes:

The search is first constrained to content matched by the view’s saved expression.
tagIds, contentTypes, and timeRange only narrow the view result set further.
If the scoped view contains no matching content, the response uses the raw search shape with an empty results array.

Content endpoints

`POST /get-available-tag-names`

Full URL: https://memex.garden/api/get-available-tag-names
Auth: authenticated user
Used for: fetching the caller’s available tag names for autocomplete, filtering, or agent prompts

Request body:

{}

Response notes:

Returns tagNames: string[].
Names are deduplicated case-insensitively and sorted alphabetically.
Includes ordinary tags and any user-available special tags.

MCP clients can use the same canonical operation through execute_action:

{
    "actionId": "tags.search",
    "input": {}
}

The completed action output includes both full tags and the compatibility tagNames list. Pass input.query to filter case-insensitively or input.limit to request a bounded result set.

`POST /list-auto-tagging-rules`

Full URL: https://memex.garden/api/list-auto-tagging-rules
Auth: authenticated user
Used for: reading the caller’s auto-tagging rule configuration

Request body:

{}

Response notes:

Returns rules, an array of auto-tagging rules.
Rule fields include id, tag_id, add_tag_ids, enabled, source flags, text_queries, ai_prompt, content_types, feed_ids, and condition_expression.

`POST /create-auto-tagging-rule`

Full URL: https://memex.garden/api/create-auto-tagging-rule
Auth: authenticated user
Used for: creating an auto-tagging rule for one or more existing tag IDs

Request body:

{
    "data": {
        "tag_id": "00000000-0000-0000-0000-000000000000",
        "enabled": false,
        "source_library": true,
        "text_queries": ["vector databases"],
        "ai_prompt": "Content about vector databases"
    }
}

Response notes:

Returns ruleId.
Provide tag_id or at least one add_tag_ids value.
If omitted, enabled defaults to false.

`POST /list-feeds`

Full URL: https://memex.garden/api/list-feeds
Auth: authenticated user
Used for: listing the caller’s subscribed RSS and YouTube feeds

Request body:

{}

Response notes:

Returns feeds: FeedListItem[].
Feed items include IDs, source URLs, display metadata, read-state timestamps, visibility, status, and initial import progress when present.
Only subscriptions owned by the authenticated user are returned.

`POST /list-handoffs`

Full URL: https://memex.garden/api/list-handoffs
MCP tool: list_handoffs
Auth: authenticated user
Used for: listing handoffs across statuses, readiness states, or time frames

If status and readyOnly are omitted, this endpoint returns handoffs across every status and approval state. Use status: "pending" for a normal poll that excludes previously processed handoffs while still showing both approved and unapproved items.

Field	Type	Required	Notes
`status`	`"pending" \| "processing" \| "processed" \| "failed" \| "archived"`	No	Omit to return every status; use `"pending"` for unprocessed handoffs.
`referenceContentEntityId`	`string`	No	Optional referenced Memex content entity ID.
`contentEntityId`	`string`	No	Alias for `referenceContentEntityId`.
`day`	`string`	No	Optional `YYYY-MM-DD` creation-day filter.
`createdAtFrom`	`string`	No	Optional inclusive ISO timestamp lower bound for creation time.
`createdAtTo`	`string`	No	Optional exclusive ISO timestamp upper bound for creation time.
`requestedDestinationText`	`string`	No	Optional exact requested target text, such as `Obsidian`.
`readyOnly`	`boolean`	No	Omit to include both approved and unapproved handoffs; `true` selects approved and `false` selects unapproved.
`limit`	`number`	No	Defaults to `100`; server caps the value.
`cursorUpdatedAt`	`string`	No	Optional cursor; returns handoffs updated before this ISO timestamp.

Pending handoffs:

{}

Handoffs created in a time frame:

{
    "createdAtFrom": "2026-07-04T00:00:00.000Z",
    "createdAtTo": "2026-07-05T00:00:00.000Z"
}

Response notes:

Returns handoffs: Handoff[].
Handoffs are operational queue records, not content entities.
This endpoint does not mark handoffs as processed.

Account and billing helper endpoints

`POST /agent-create-user`

Full URL: https://memex.garden/api/agent-create-user
Auth: x-agent-service-token
Used for: agent-assisted signup on behalf of a human

Field	Type	Required	Notes
`targetUserEmail`	`string`	Yes	Email address to create the account for.
`targetUserName`	`string`	No	Optional display name.
`targetUserPicture`	`string`	No	Optional avatar URL.

`POST /get-available-plans`

Full URL: https://memex.garden/api/get-available-plans
Auth: none
Used for: fetching the live pricing catalog before checkout

Request body:

{}

`POST /checkout`

Full URL: https://memex.garden/api/checkout
Auth: X-Api-Key: <apiKey> or an accepted Memex bearer token
Used for: buying one-time credit plans from an agent runtime

Field	Type	Required	Notes
`planId`	`string`	No	Required unless `variantId` is supplied.
`variantId`	`string`	No	Required unless `planId` is supplied.
`payment.provider`	`stripe`	Yes	Only Stripe is supported.
`payment.sharedPaymentToken`	`string`	Yes	Stripe Shared Payment Token issued to Memex.Garden.

Use /checkout for one-time plans. For subscription plans, send the user to https://memex.garden/pricing.

MCP protocol request shape

MCP requests go to: https://memex.garden/api/mcp

List tools

{
    "jsonrpc": "2.0",
    "id": "tools-list-1",
    "method": "tools/list",
    "params": {}
}

Call a tool

{
    "jsonrpc": "2.0",
    "id": "call-1",
    "method": "tools/call",
    "params": {
        "name": "search_content",
        "arguments": {
            "query": "vector databases",
            "limit": 5
        }
    }
}

Auth and signup: Authentication
NPM client: SDK
Credit purchase flow: Buy credits
Parsed response contracts: Response shape
Agent-facing overview: MCP

General

API reference

Plugins

Surface map

Core operations

Search saved content

Parameters

Search behavior

LLM vs full response options

Feed-focused search

Available `contentTypes` values

Save content or a public URL

Parameters

View endpoints

`POST /create-view`

`POST /list-views`

`POST /execute-view-search`

Content endpoints

`POST /get-available-tag-names`

`POST /list-auto-tagging-rules`

`POST /create-auto-tagging-rule`

`POST /list-feeds`

`POST /list-handoffs`

Account and billing helper endpoints

`POST /agent-create-user`

`POST /get-available-plans`

`POST /checkout`

MCP protocol request shape

List tools

Call a tool

​Surface map

​Core operations

​Search saved content

​Parameters

​Search behavior

​LLM vs full response options

​Feed-focused search

​Available contentTypes values

​Save content or a public URL

​Parameters

​Create a public sharing link

​List public sharing links

​View endpoints

​POST /create-view

​POST /list-views

​POST /execute-view-search

​Content endpoints

​POST /get-available-tag-names

​POST /list-auto-tagging-rules

​POST /create-auto-tagging-rule

​POST /list-feeds

​POST /list-handoffs

​Account and billing helper endpoints

​POST /agent-create-user

​POST /get-available-plans

​POST /checkout

​MCP protocol request shape

​List tools

​Call a tool

​Related docs

Surface map

Core operations

Search saved content

Parameters

Search behavior

LLM vs full response options

Feed-focused search

Available `contentTypes` values

Save content or a public URL

Parameters

Create a public sharing link

List public sharing links

View endpoints

`POST /create-view`

`POST /list-views`

`POST /execute-view-search`

Content endpoints

`POST /get-available-tag-names`

`POST /list-auto-tagging-rules`

`POST /create-auto-tagging-rule`

`POST /list-feeds`

`POST /list-handoffs`

Account and billing helper endpoints

`POST /agent-create-user`

`POST /get-available-plans`

`POST /checkout`

MCP protocol request shape

List tools

Call a tool

Related docs