Eden Highlights & captures API

openapi: 3.2.0
info:
  title: Eden workspace Highlights & captures API
  version: 1.0.0
  summary: Every Eden MCP tool as a plain HTTPS call.
  description: 'Each tool in Eden''s MCP server (`https://mcp.eden.so/mcp`) also runs as `POST /v1/tools/` with its arguments as the JSON body: Discover search, creator analysis, the ads library, scheduling, analytics, boards, notes, tables, Custom AIs, and the store.


    **Sign in:** `Authorization: Bearer `, an Eden API key from Settings → API (`eden_pat_…`) or an OAuth access token. Read-only keys can''t run write tools, and a Custom key only sees the tools its access allows.


    **Credits and limits:** the same as MCP. Research tools cost 0.1 to 0.5 AI credits a call; saving, scheduling, and reading your own workspace are free. 120 calls a minute per key, shared with MCP.


    **Answers:** the tool''s own `{ ok: true, ... }` or `{ ok: false, status, message }`, with the HTTP status mirroring `status`.


    Invite-only tools are left out of this file; `GET /v1/tools` lists what a key can use. The store API (sales, customers, products, webhooks) is a separate spec: https://api.eden.so/store-app/v1/openapi.json'
  contact:
    name: Eden
    url: https://eden.so/help/api/use-the-eden-api/
  termsOfService: https://eden.so/terms/
servers:
- url: https://mcp.eden.so
  description: Eden workspace API
security:
- apiKey: []
tags:
- name: Highlights & captures
paths:
  /v1/tools/eden_search_captures:
    post:
      operationId: eden_search_captures
      summary: Search captures
      description: 'The user''s quick captures — notes, links, and media / voice-note clippings saved from the Eden mobile app, share sheet, or quick-capture panel to act on later. TWO MODES: pass `q` to keyword-search note text, link titles/URLs, and media filenames (''find what I captured about X''); omit `q` to LIST recent captures (''what have I captured lately''), optionally filtered by `status` and paginated with `offset`. Each capture returns its type (text/link/media), its text, and link/media metadata. Audio / voice notes are metadata only — no transcript.'
      tags:
      - Highlights & captures
      x-read-only: true
      x-destructive: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                workspaceId:
                  description: Workspace id (eden_list_workspaces). Omit for the default.
                  type: string
                  minLength: 1
                q:
                  description: Keyword(s) to match against capture text, link title/URL, and media filename. Omit to list recent captures instead of searching.
                  type: string
                  minLength: 1
                  maxLength: 256
                limit:
                  description: Max results. Default 10 when searching, 20 when listing (search caps at 50).
                  type: integer
                  minimum: 1
                  maximum: 200
                offset:
                  description: 'List mode only: pagination offset. Default 0.'
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                status:
                  description: 'List mode only: `active` = not yet filed anywhere (default). `sent` = already promoted to a board. `archived`. `all` = every status.'
                  type: string
                  enum:
                  - active
                  - archived
                  - sent
                  - all
      responses:
        '200':
          description: 'The tool''s result: `{ ok: true, ... }`. Tools that answer plain text come back as `{ ok: true, text }`.'
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/Failure'
        '401':
          $ref: '#/components/responses/Failure'
        '402':
          $ref: '#/components/responses/Failure'
        '403':
          $ref: '#/components/responses/Failure'
        '404':
          $ref: '#/components/responses/Failure'
        '409':
          $ref: '#/components/responses/Failure'
        '422':
          $ref: '#/components/responses/Failure'
        '429':
          $ref: '#/components/responses/Failure'
        '500':
          $ref: '#/components/responses/Failure'
        '503':
          $ref: '#/components/responses/Failure'
  /v1/tools/eden_search_highlights:
    post:
      operationId: eden_search_highlights
      summary: Search highlights
      description: 'The user''s highlights — their personal swipe file of quotes saved from books, articles, podcasts, and tweets (synced from Readwise, Kindle, or highlighted in Eden''s reader). TWO MODES: pass `q` to keyword-search highlight text, the user''s notes, and book title/author (''find my highlights about X''); omit `q` to LIST recent highlights (''what have I highlighted lately''), optionally scoped with `source` to everything from one book/article/podcast and ordered by `orderBy`. Each highlight returns its text, note, source, link, and — when it has a Library card in the workspace — its `itemId` (save highlights to boards by `itemId`, never by url — see server instructions). Empty if no highlight source is connected or nothing matches.'
      tags:
      - Highlights & captures
      x-read-only: true
      x-destructive: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                workspaceId:
                  description: Workspace id from `eden_list_workspaces`, used to resolve each highlight's Library `itemId`. Optional when EDEN_WORKSPACE_ID is configured.
                  type: string
                  minLength: 1
                q:
                  description: Keyword(s) to match against highlight text, notes, and book title/author. Omit to list recent highlights instead of searching.
                  type: string
                  minLength: 1
                  maxLength: 256
                source:
                  description: 'Restrict to one source: substring-matched (case-insensitive) against book/article title and author.'
                  type: string
                  minLength: 1
                  maxLength: 256
                limit:
                  description: Max results. Default 10 when searching, 20 when listing (search caps at 50).
                  type: integer
                  minimum: 1
                  maximum: 200
                offset:
                  description: 'List mode only: pagination offset. Default 0.'
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                orderBy:
                  description: 'List mode only: `recent` = most recently synced (default), `highlighted` = by the date the user highlighted it in the source.'
                  type: string
                  enum:
                  - recent
                  - highlighted
      responses:
        '200':
          description: 'The tool''s result: `{ ok: true, ... }`. Tools that answer plain text come back as `{ ok: true, text }`.'
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/Failure'
        '401':
          $ref: '#/components/responses/Failure'
        '402':
          $ref: '#/components/responses/Failure'
        '403':
          $ref: '#/components/responses/Failure'
        '404':
          $ref: '#/components/responses/Failure'
        '409':
          $ref: '#/components/responses/Failure'
        '422':
          $ref: '#/components/responses/Failure'
        '429':
          $ref: '#/components/responses/Failure'
        '500':
          $ref: '#/components/responses/Failure'
        '503':
          $ref: '#/components/responses/Failure'
components:
  schemas:
    Failure:
      type: object
      required:
      - ok
      - status
      - message
      properties:
        ok:
          type: boolean
          const: false
        status:
          type: string
          description: auth-expired (401), upgrade-required (402), forbidden / not-enabled (403), not-found (404), conflict (409), invalid / needs-input / missing-workspace / confirmation-required (422), quota-exceeded / rate-limited (429), unreachable / unavailable (503), error (500).
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        outOfCredits:
          type: boolean
        upgradeUrl:
          type: string
  responses:
    Failure:
      description: The call failed. `status` and `message` say why and what to do.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: eden_pat_…
      description: An Eden API key from Settings → API, or an OAuth access token.