Karakeep

Karakeep API

Karakeep API as documented publicly: 28 operations. Contract generated from the documentation by API Evangelist (2026-10-28); not the provider's own document.

GitHub OpenAPI

Operations 28

PUT /admin/users/{userid} Update a user's role, bookmark quota, storage quota, or browser crawling setting. #
POST /assets Upload a new asset #
GET /backups Get all backups #
GET /bookmarks Get all bookmarks #
POST /bookmarks Create a new bookmark #
DELETE /bookmarks/{bookmarkid} Permanently delete a bookmark and all its associated data (tags, highlights, assets). #
GET /bookmarks/{bookmarkid} Retrieve a single bookmark by its ID, including its tags, content, and assets. #
PATCH /bookmarks/{bookmarkid} Partially update a bookmark. #
GET /bookmarks/{bookmarkid}/lists Retrieve all lists that contain the specified bookmark. #
POST /bookmarks/{bookmarkid}/summarize Trigger AI summarization for a bookmark. #
GET /highlights Get all highlights #
POST /highlights Create a new highlight #
DELETE /highlights/{highlightid} Delete a highlight by its ID. #
GET /highlights/{highlightid} Retrieve a single highlight by its ID. #
PATCH /highlights/{highlightid} Partially update a highlight. Supports changing the color or note. #
GET /lists Get all lists #
POST /lists Create a new list #
DELETE /lists/{listid} Delete a list. #
GET /lists/{listid} Retrieve a single list by its ID. #
PATCH /lists/{listid} Partially update a list. Only the fields provided in the request body will be updated. #
GET /lists/{listid}/bookmarks Get bookmarks in a list #
GET /tags Retrieve a paginated list of all tags. #
POST /tags Create a new tag. #
DELETE /tags/{tagid} Delete a tag. #
GET /tags/{tagid} Get a single tag #
PATCH /tags/{tagid} Rename a tag. The new name will be normalized and trimmed. #
GET /tags/{tagid}/bookmarks Get bookmarks with a tag #
GET /users/me Get current user info #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/karakeep/openapi/_ae-authored/karakeep-openapi-generated.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-patch-bookmarks-bookmarkid-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-put-admin-users-userid-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-post-bookmarks-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-post-highlights-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-post-lists-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/karakeep/json-schema/karakeep-post-bookmarks-bookmarkid-summarize-response-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/karakeep:karakeep-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

karakeep-openapi-generated.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Karakeep API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 28 operation(s) read from 40 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Karakeep has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 28
    pages-with-code: 0
    pages-read: 40
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.karakeep.com/api/get-tag
  - https://docs.karakeep.com/api/get-list
  - https://docs.karakeep.com/api/list-tags
  - https://docs.karakeep.com/api/create-tag
  - https://docs.karakeep.com/api/delete-tag
  - https://docs.karakeep.com/api/list-lists
  - https://docs.karakeep.com/api/update-tag
  - https://docs.karakeep.com/api/create-list
  - https://docs.karakeep.com/api/delete-list
  - https://docs.karakeep.com/api/update-list
  - https://docs.karakeep.com/api/get-bookmark
  - https://docs.karakeep.com/api/list-backups
  - https://docs.karakeep.com/api/upload-asset
  - https://docs.karakeep.com/api/get-highlight
  - https://docs.karakeep.com/api/list-bookmarks
  - https://docs.karakeep.com/next/api/list-tags
  - https://docs.karakeep.com/api/create-bookmark
  - https://docs.karakeep.com/api/delete-bookmark
  - https://docs.karakeep.com/api/list-highlights
  - https://docs.karakeep.com/api/update-bookmark
  - https://docs.karakeep.com/next/api/list-lists
  - https://docs.karakeep.com/api/create-highlight
  - https://docs.karakeep.com/api/delete-highlight
  - https://docs.karakeep.com/api/get-current-user
  - https://docs.karakeep.com/api/search-bookmarks
  - https://docs.karakeep.com/api/update-highlight
  - https://docs.karakeep.com/api/admin-update-user
  - https://docs.karakeep.com/api/get-tag-bookmarks
  - https://docs.karakeep.com/next/api/list-backups
  - https://docs.karakeep.com/next/api/upload-asset
  - https://docs.karakeep.com/v0.31.0/api/list-tags
  - https://docs.karakeep.com/v0.32.0/api/list-tags
  - https://docs.karakeep.com/v0.33.0/api/list-tags
  - https://docs.karakeep.com/api/check-bookmark-url
  - https://docs.karakeep.com/api/get-bookmark-lists
  - https://docs.karakeep.com/api/get-list-bookmarks
  - https://docs.karakeep.com/api/summarize-bookmark
  - https://docs.karakeep.com/v0.31.0/api/list-lists
  - https://docs.karakeep.com/v0.32.0/api/list-lists
  - https://docs.karakeep.com/v0.33.0/api/list-lists
paths:
  /admin/users/{userid}:
    put:
      operationId: put_admin_users_userid
      tags:
      - Admin
      summary: Update a user's role, bookmark quota, storage quota, or browser crawling setting.
      x-source: https://docs.karakeep.com/api/admin-update-user
      parameters:
      - name: userid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutAdminUsersUseridResponse'
      x-evidence:
        kind: documentation
  /assets:
    post:
      operationId: post_assets
      tags:
      - Assets
      summary: Upload a new asset
      x-source: https://docs.karakeep.com/api/upload-asset
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAssetsResponse'
      x-evidence:
        kind: documentation
  /backups:
    get:
      operationId: get_backups
      tags:
      - Backups
      summary: Get all backups
      description: Retrieve a list of all backups for the authenticated user, including their status and metadata.
      x-source: https://docs.karakeep.com/api/list-backups
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /bookmarks:
    get:
      operationId: get_bookmarks
      tags:
      - Bookmarks
      summary: Get all bookmarks
      x-source: https://docs.karakeep.com/api/list-bookmarks
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBookmarksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_bookmarks
      tags:
      - Bookmarks
      summary: Create a new bookmark
      x-source: https://docs.karakeep.com/api/create-bookmark
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBookmarksResponse'
      x-evidence:
        kind: documentation
  /bookmarks/{bookmarkid}:
    delete:
      operationId: delete_bookmarks_bookmarkid
      tags:
      - Bookmarks
      summary: Permanently delete a bookmark and all its associated data (tags, highlights, assets).
      x-source: https://docs.karakeep.com/api/delete-bookmark
      parameters:
      - name: bookmarkid
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_bookmarks_bookmarkid
      tags:
      - Bookmarks
      summary: Retrieve a single bookmark by its ID, including its tags, content, and assets.
      x-source: https://docs.karakeep.com/api/get-bookmark
      parameters:
      - name: bookmarkid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_bookmarks_bookmarkid
      tags:
      - Bookmarks
      summary: Partially update a bookmark.
      x-source: https://docs.karakeep.com/api/update-bookmark
      parameters:
      - name: bookmarkid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBookmarksBookmarkidRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchBookmarksBookmarkidResponse'
      x-evidence:
        kind: documentation
  /bookmarks/{bookmarkid}/lists:
    get:
      operationId: get_bookmarks_bookmarkid_lists
      tags:
      - Bookmarks
      summary: Retrieve all lists that contain the specified bookmark.
      x-source: https://docs.karakeep.com/api/get-bookmark-lists
      parameters:
      - name: bookmarkid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /bookmarks/{bookmarkid}/summarize:
    post:
      operationId: post_bookmarks_bookmarkid_summarize
      tags:
      - Bookmarks
      summary: Trigger AI summarization for a bookmark.
      x-source: https://docs.karakeep.com/api/summarize-bookmark
      parameters:
      - name: bookmarkid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBookmarksBookmarkidSummarizeResponse'
      x-evidence:
        kind: documentation
  /highlights:
    get:
      operationId: get_highlights
      tags:
      - Highlights
      summary: Get all highlights
      description: Retrieve a paginated list of all highlights across all bookmarks for the authenticated user.
      x-source: https://docs.karakeep.com/api/list-highlights
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_highlights
      tags:
      - Highlights
      summary: Create a new highlight
      x-source: https://docs.karakeep.com/api/create-highlight
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostHighlightsResponse'
      x-evidence:
        kind: documentation
  /highlights/{highlightid}:
    delete:
      operationId: delete_highlights_highlightid
      tags:
      - Highlights
      summary: Delete a highlight by its ID.
      x-source: https://docs.karakeep.com/api/delete-highlight
      parameters:
      - name: highlightid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_highlights_highlightid
      tags:
      - Highlights
      summary: Retrieve a single highlight by its ID.
      x-source: https://docs.karakeep.com/api/get-highlight
      parameters:
      - name: highlightid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_highlights_highlightid
      tags:
      - Highlights
      summary: Partially update a highlight. Supports changing the color or note.
      x-source: https://docs.karakeep.com/api/update-highlight
      parameters:
      - name: highlightid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /lists:
    get:
      operationId: get_lists
      tags:
      - Lists
      summary: Get all lists
      description: Retrieve all bookmark lists for the authenticated user, including both manual and smart lists.
      x-source: https://docs.karakeep.com/api/list-lists
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_lists
      tags:
      - Lists
      summary: Create a new list
      x-source: https://docs.karakeep.com/api/create-list
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostListsResponse'
      x-evidence:
        kind: documentation
  /lists/{listid}:
    delete:
      operationId: delete_lists_listid
      tags:
      - Lists
      summary: Delete a list.
      description: Delete a list. This removes the list only — bookmarks within it are not deleted.
      x-source: https://docs.karakeep.com/api/delete-list
      parameters:
      - name: listid
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_lists_listid
      tags:
      - Lists
      summary: Retrieve a single list by its ID.
      x-source: https://docs.karakeep.com/api/get-list
      parameters:
      - name: listid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_lists_listid
      tags:
      - Lists
      summary: Partially update a list. Only the fields provided in the request body will be updated.
      x-source: https://docs.karakeep.com/api/update-list
      parameters:
      - name: listid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /lists/{listid}/bookmarks:
    get:
      operationId: get_lists_listid_bookmarks
      tags:
      - Lists
      summary: Get bookmarks in a list
      description: Retrieve a paginated list of bookmarks within the specified list. For smart lists, bookmarks are computed from the list's query.
      x-source: https://docs.karakeep.com/api/get-list-bookmarks
      parameters:
      - name: listid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /tags:
    get:
      operationId: get_tags
      tags:
      - Tags
      summary: Retrieve a paginated list of all tags.
      x-source: https://docs.karakeep.com/api/list-tags
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Filter tags by name.
      - name: attached_by
        in: query
        required: false
        schema:
          type: string
        description: Filter tags by attached‑by source.
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: Sort tags by name, usage count, or relevance.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_tags
      tags:
      - Tags
      summary: Create a new tag.
      x-source: https://docs.karakeep.com/api/create-tag
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTagsResponse'
      x-evidence:
        kind: documentation
  /tags/{tagid}:
    delete:
      operationId: delete_tags_tagid
      tags:
      - Tags
      summary: Delete a tag.
      description: Delete a tag. This removes the tag from all bookmarks it was attached to.
      x-source: https://docs.karakeep.com/api/delete-tag
      parameters:
      - name: tagid
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_tags_tagid
      tags:
      - Tags
      summary: Get a single tag
      description: Retrieve a single tag by its ID, including the number of bookmarks using it.
      x-source: https://docs.karakeep.com/api/get-tag
      parameters:
      - name: tagid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_tags_tagid
      tags:
      - Tags
      summary: Rename a tag. The new name will be normalized and trimmed.
      x-source: https://docs.karakeep.com/api/update-tag
      parameters:
      - name: tagid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchTagsTagidResponse'
      x-evidence:
        kind: documentation
  /tags/{tagid}/bookmarks:
    get:
      operationId: get_tags_tagid_bookmarks
      tags:
      - Tags
      summary: Get bookmarks with a tag
      description: Retrieve a paginated list of all bookmarks that have the specified tag attached.
      x-source: https://docs.karakeep.com/api/get-tag-bookmarks
      parameters:
      - name: tagid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /users/me:
    get:
      operationId: get_users_me
      tags:
      - Users
      summary: Get current user info
      description: Retrieve profile information for the currently authenticated user, including their name, email, and avatar.
      x-source: https://docs.karakeep.com/api/get-current-user
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PutAdminUsersUseridResponse:
      type: object
      properties:
        '200':
          type: string
          description: User updated successfully.
        '400':
          type: string
          description: Bad request — invalid input data or attempted to update own user.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
        '403':
          type: string
          description: Forbidden — admin access required.
        '404':
          type: string
          description: User not found.
    PostAssetsResponse:
      type: object
      properties:
        '200':
          type: string
          description: The asset was uploaded successfully. Returns metadata about the uploaded asset.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
    GetBookmarksResponse:
      type: object
      properties:
        '200':
          type: string
          description: A paginated list of bookmarks.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
    PostBookmarksResponse:
      type: object
      properties:
        '200':
          type: string
          description: A bookmark with this URL already exists. The existing bookmark is returned.
        '201':
          type: string
          description: The bookmark was created successfully.
        '400':
          type: string
          description: Bad request — invalid input data.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
    PatchBookmarksBookmarkidRequest:
      type: object
      properties:
        title:
          type: string
          description: 'Common field: title of the bookmark.'
        note:
          type: string
          description: 'Common field: note attached to the bookmark.'
        archived:
          type: boolean
          description: 'Common field: whether the bookmark is archived.'
        favourited:
          type: boolean
          description: 'Common field: whether the bookmark is favourited.'
        type-specific fields:
          type: object
          description: Additional fields specific to the bookmark type.
    PatchBookmarksBookmarkidResponse:
      type: object
      properties:
        '200':
          type: string
          description: The updated bookmark.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
        '404':
          type: string
          description: Bookmark not found.
    PostBookmarksBookmarkidSummarizeResponse:
      type: object
      properties:
        '200':
          type: string
          description: The bookmark with the updated summary.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
        '404':
          type: string
          description: Bookmark not found.
    PostHighlightsResponse:
      type: object
      properties:
        '201':
          type: string
          description: The created highlight.
        '400':
          type: string
          description: Bad request — invalid offsets or missing required fields.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
        '404':
          type: string
          description: Bookmark not found — the specified bookmarkId does not exist.
    PostListsResponse:
      type: object
      properties:
        '201':
          type: string
          description: The created list.
        '400':
          type: string
          description: Bad request — invalid input data (e.g., smart list missing query, or manual list with a query).
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
    PostTagsResponse:
      type: object
      properties:
        '201':
          type: string
          description: The created tag.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
    PatchTagsTagidResponse:
      type: object
      properties:
        '200':
          type: string
          description: The updated tag.
        '401':
          type: string
          description: Unauthorized — the Bearer token is missing, invalid, or expired.
        '404':
          type: string
          description: Tag not found.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Admin
- name: Assets
- name: Backups
- name: Bookmarks
- name: Highlights
- name: Lists
- name: Tags
- name: Users