Recall API and MCP server Let your AI agent fill and tidy your Recall.

ToolWhat it doesAccess

• search_cards Find cards by meaning or keyword, optionally within a tag, date range or source. read

  Runs Recall's combined semantic and keyword search over your cards and returns the matching text chunks grouped by card. mode focused returns fewer cards with more chunks each and suits answering a question; exhaustive returns more cards with a few preview chunks each and suits listing. Pass card_id to search inside one card. tag_ids match with OR logic. Read-only.

  MCP callrecall_read → search_cards

  REST endpointGET https://cotlet.dev/api/v1/recall/cards/search

  Parameters

  Parameters: search_cards

  Name	Type	Description
  q string required	string	Search query.
  mode enum	enum	focused or exhaustive. Default: focused.
  card_id string	string	Search inside this card only.
  tag_ids string[]	string[]	Only cards with one of these tags. IDs from list_tags.
  date_from date	date	Only cards saved on or after this date.
  date_to date	date	Only cards saved on or before this date.
  source_url_contains string	string	Only cards whose source URL contains this text, e.g. a domain.

  Example input

  {
    "q": "q"
  }

  Example response

  {
    "documents": [
      {
        "card_id": "card_8f2a61",
        "title": "How we price a B2B SaaS",
        "created_at": "Oct 14, 2026",
        "source_url": "https://blog.example.com/how-we-price",
        "chunks": [
          {
            "chunk_id": "chunk_004",
            "content": "Start with three tiers and anchor on the middle one.",
            "source": "page 2"
          }
        ]
      }
    ],
    "total_cards": 1,
    "total_chunks": 1
  }

• list_cards Cards in your knowledge base, filtered by tag, date or source URL. read

  Returns the cards that match the filters, each with id, title, created_at and, when Recall has them, image and source_url. Without filters it returns all of your cards, so pass a date range or a tag on a large knowledge base. A card with no source URL (a note) is not matched by source_url_contains. Use card_id from the result in get_card and the write tools.

  MCP callrecall_read → list_cards

  REST endpointGET https://cotlet.dev/api/v1/recall/cards

  Parameters

  Parameters: list_cards

  Name	Type	Description
  tag_ids string[]	string[]	Only cards with one of these tags. IDs from list_tags.
  date_from date	date	Only cards saved on or after this date.
  date_to date	date	Only cards saved on or before this date.
  source_url_contains string	string	Only cards whose source URL contains this text, e.g. a domain.

  Example response

  {
    "results": [
      {
        "card_id": "card_8f2a61",
        "title": "How we price a B2B SaaS",
        "created_at": "Oct 14, 2026",
        "source_url": "https://blog.example.com/how-we-price"
      },
      {
        "card_id": "card_c40b19",
        "title": "Notes on onboarding calls",
        "created_at": "Oct 12, 2026"
      }
    ],
    "total_count": 2
  }

• get_card The content of one card as text chunks, with its source. read

  Returns one card with its content chunks and source URL. Chunks carry a source such as a page number and, for video and podcasts, timestamps. Pass focus_query to get the chunks that match a topic instead of a generic selection, which helps on long cards. max_chunks defaults to 20 and goes up to 50. A card that does not exist returns APP_NOT_FOUND.

  MCP callrecall_read → get_card

  REST endpointGET https://cotlet.dev/api/v1/recall/cards/{card_id}

  Parameters

  Parameters: get_card

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.
  focus_query string	string	Return the chunks that match this query.
  max_chunks integer	integer	1 to 50. Default: 20.

  Example input

  {
    "card_id": "card_8c41d2"
  }

  Example response

  {
    "card_id": "card_8f2a61",
    "title": "How we price a B2B SaaS",
    "created_at": "Oct 14, 2026",
    "source_url": "https://blog.example.com/how-we-price",
    "chunks": [
      {
        "chunk_id": "chunk_004",
        "content": "Start with three tiers and anchor on the middle one.",
        "source": "page 2"
      },
      {
        "chunk_id": "chunk_007",
        "content": "Annual billing at a 20% discount lifts retention.",
        "source": "page 3"
      }
    ]
  }

• get_knowledge_base_stats Total cards, date range, top tags and common sources of your knowledge base. read

  Gives an overview of the whole knowledge base: the number of cards, the date of the oldest and newest card, the most used tags and the domains you save from most. Use it to decide where to look first. Read-only.

  MCP callrecall_read → get_knowledge_base_stats

  REST endpointGET https://cotlet.dev/api/v1/recall/knowledge-base-stats

  Parameters

  No parameters.

  Example response

  {
    "total_cards": 412,
    "oldest_card": "Mar 3, 2025",
    "newest_card": "Oct 24, 2026",
    "top_tags": [
      {
        "name": "Reading",
        "cards": 31
      },
      {
        "name": "Business/Pricing",
        "cards": 9
      }
    ],
    "top_sources": [
      {
        "domain": "youtube.com",
        "cards": 74
      },
      {
        "domain": "blog.example.com",
        "cards": 22
      }
    ]
  }

• export_card_markdown The card as a Markdown file, the same as Export to Markdown in the card menu. read

  Returns one card as Markdown text. It is the single-card export from the card menu. The export of the whole knowledge base in Settings is a zip file and is not available as a tool. Nothing changes in Recall.

  MCP callrecall_read → export_card_markdown

  REST endpointGET https://cotlet.dev/api/v1/recall/cards/{card_id}/markdown/export

  Parameters

  Parameters: export_card_markdown

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.

  Example input

  {
    "card_id": "card_8c41d2"
  }

  Example response

  {
    "card_id": "card_8f2a61",
    "filename": "how-we-price-a-b2b-saas.md",
    "markdown": "# How we price a B2B SaaS\n\nStart with three tiers and anchor on the middle one.\n"
  }

ToolWhat it doesAccess

• save_url Save a web page, YouTube video, podcast or PDF link as a new card. write

  Does what Add > paste a URL does: it creates a card from one link. Recall adds a tag on its own and, by default, writes a concise summary into the Notebook; both follow your Recall settings. On the Free plan a summary counts toward the 10 AI summaries per month. Returns the new card_id. Saving reaches no one and one delete_card call removes the card, so it does not wait for your OK.

  MCP callrecall_write → save_url

  REST endpointPOST https://cotlet.dev/api/v1/recall/url/save

  Parameters

  Parameters: save_url

  Name	Type	Description
  url string required	string	The link to save. One URL per call.

  Example input

  {
    "url": "https://blog.example.com/pricing-psychology"
  }

  Example response

  {
    "card_id": "card_e91d07",
    "title": "Pricing psychology for SaaS",
    "source_url": "https://blog.example.com/pricing-psychology",
    "status": "saved",
    "tags": [
      "Business/Pricing"
    ]
  }

• create_note Create a new note card with a title and text. write

  Does what the pen button does: it creates a card with an empty Notebook and fills it with your text. The text is plain, without images or tables. The note gets the same tags, connections and AI features as any card. Writing a note reaches no one and delete_card undoes it, so it does not wait for your OK.

  MCP callrecall_write → create_note

  REST endpointPOST https://cotlet.dev/api/v1/recall/notes

  Parameters

  Parameters: create_note

  Name	Type	Description
  title string required	string	Title of the note.
  body string required	string	Text of the note.

  Example input

  {
    "title": "title",
    "body": "body"
  }

  Example response

  {
    "card_id": "card_5a3c88",
    "title": "Pricing pages compared",
    "status": "created"
  }

• delete_card Permanently delete one card. writeasks first

  Deletes one card with its Notebook, summary and connections. Recall has no recycle bin, so a deleted card cannot be recovered, and Cotlet cannot bring it back. Use export_card_markdown first if you may want it later. Returns the deleted card_id and title. By default you confirm each call; you can switch that off for this tool.

  MCP callrecall_write → delete_card

  REST endpointDELETE https://cotlet.dev/api/v1/recall/cards/{card_id}

  Parameters

  Parameters: delete_card

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.

  Example input

  {
    "card_id": "card_8c41d2"
  }

  Example response

  {
    "card_id": "card_c40b19",
    "title": "Notes on onboarding calls",
    "status": "deleted"
  }

ToolWhat it doesAccess

• list_tags Your tags with the number of cards under each; nested tags appear as Parent/Child. read

  Returns every tag in your knowledge base with its ID and how many cards carry it. Nested tags are written with a slash, for example Movies/Thrillers. Use the IDs as tag_ids in list_cards and search_cards. Check this list before tagging so the agent reuses a tag instead of creating a near-duplicate.

  MCP callrecall_read → list_tags

  REST endpointGET https://cotlet.dev/api/v1/recall/tags

  Parameters

  No parameters.

  Example response

  {
    "tags": [
      {
        "tag_id": "3b7e2f10-6c1a-4f55-9d3e-2a8c1f0b7d41",
        "name": "Business/Pricing",
        "cards": 9
      },
      {
        "tag_id": "9d1c5a22-4e7b-41a8-b6f3-0c5e8a1d2b93",
        "name": "Reading",
        "cards": 31
      }
    ]
  }

• add_tags_to_card Add one or more tags to a card; an unknown tag is created. write

  Adds tags to one card. If a tag with that name exists, Recall uses it; otherwise it creates it. Type a slash to nest a tag, so Movies/Thrillers puts Thrillers under Movies. A card can have many tags, and the tags already on it stay. Returns the full tag list of the card. Tagging reaches no one and remove_tags_from_card undoes it, so it does not wait for your OK.

  MCP callrecall_write → add_tags_to_card

  REST endpointPOST https://cotlet.dev/api/v1/recall/cards/{card_id}/tags-to-cards

  Parameters

  Parameters: add_tags_to_card

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.
  tags string[] required	string[]	Tag names. Use / to nest, e.g. Business/Pricing.

  Example input

  {
    "card_id": "card_8c41d2",
    "tags": [
      "tags"
    ]
  }

  Example response

  {
    "card_id": "card_e91d07",
    "tags": [
      "Business/Pricing",
      "Reading"
    ]
  }

• remove_tags_from_card Take one or more tags off a card. write

  Removes the named tags from one card. The card, its other tags and the tags themselves stay. A name the card does not carry is skipped and listed in not_found. Returns the tags left on the card. Reaches no one and add_tags_to_card undoes it, so it does not wait for your OK.

  MCP callrecall_write → remove_tags_from_card

  REST endpointDELETE https://cotlet.dev/api/v1/recall/cards/{card_id}/tags-from-cards

  Parameters

  Parameters: remove_tags_from_card

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.
  tags string[] required	string[]	Tag names to remove.

  Example input

  {
    "card_id": "card_8c41d2",
    "tags": [
      "tags"
    ]
  }

  Example response

  {
    "card_id": "card_e91d07",
    "tags": [
      "Reading"
    ],
    "not_found": []
  }

• list_card_connections The keywords and linked cards in a card's Connections tab. read

  Returns what the Connections tab of a card shows: its keywords, each with the number of other cards that mention it. Recall extracts the keywords itself when a card is created, and links you added with [[ in the Notebook show up here too. A card that only just got saved can show few keywords until Recall finishes processing it.

  MCP callrecall_read → list_card_connections

  REST endpointGET https://cotlet.dev/api/v1/recall/card-connections

  Parameters

  Parameters: list_card_connections

  Name	Type	Description
  card_id string required	string	Card ID from list_cards or search_cards.

  Example input

  {
    "card_id": "card_8c41d2"
  }

  Example response

  {
    "card_id": "card_8f2a61",
    "connections": [
      {
        "keyword": "Pricing tiers",
        "cards": 7
      },
      {
        "keyword": "Annual billing",
        "cards": 4
      },
      {
        "keyword": "Anchoring",
        "cards": 2
      }
    ]
  }

ToolWhat it doesAccess

• get_review_status Questions ready for review now, due this week and how many sit in each knowledge stage. read

  Returns what the Review dashboard shows: how many questions are ready now, how many are due this week and your streak. by_stage counts every question in the five stages Recall uses: New, Learning, Practiced, Confident and Mastered. It only reports; it does not answer or start a review.

  MCP callrecall_read → get_review_status

  REST endpointGET https://cotlet.dev/api/v1/recall/review-status

  Parameters

  No parameters.

  Example response

  {
    "ready_now": 18,
    "due_this_week": 42,
    "streak_days": 6,
    "total_questions": 120,
    "by_stage": {
      "new": 14,
      "learning": 22,
      "practiced": 31,
      "confident": 36,
      "mastered": 17
    }
  }