{"openapi":"3.1.0","info":{"title":"Hypothesis (BYOK) API","version":"0.1.0","description":"Hypothesis (BYOK) lets an AI assistant read your own Hypothesis data through the Hypothesis API with a key you supply (Hypothesis API token). Read-only: 8 tools (get_profile, list_my_groups, search_annotations, get_annotation, get_group, list_groups, list_group_members, list_group_annotations). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hypothesis.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hypothesis/docs"},"termsOfService":"https://connectorbay.com/byok-hypothesis/terms"},"servers":[{"url":"https://byok-hypothesis.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hypothesis/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_profile":{"post":{"operationId":"get_profile","summary":"Show the Hypothesis account the token belongs to: user id, authority and display name. Use for \"Which Hypothesis account","description":"Show the Hypothesis account the token belongs to: user id, authority and display name. Use for \"Which Hypothesis account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_profileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_my_groups":{"post":{"operationId":"list_my_groups","summary":"List the groups the account is a member of, with group id, name, type (private, open or restricted) and link. Use for \"W","description":"List the groups the account is a member of, with group id, name, type (private, open or restricted) and link. Use for \"Which Hypothesis groups am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_my_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_annotations":{"post":{"operationId":"search_annotations","summary":"Search annotations visible to the account (own, group and public ones) by user, URL, group, tag or text, newest first by","description":"Search annotations visible to the account (own, group and public ones) by user, URL, group, tag or text, newest first by default. Use for \"What have I highlighted and annotated about 'ribosome' on Hypothesis\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"any":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword matched against quote, tags, text and URL of an annotation.","title":"Any"},"user":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only annotations by this user id, in the form acct:username@hypothes.is.","title":"User"},"uri":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only annotations of this exact page URL (or DOI / PDF fingerprint).","title":"Uri"},"group":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only annotations in this group id.","title":"Group"},"tag":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only annotations carrying this tag.","title":"Tag"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to look for in the annotation comment text.","title":"Text"},"quote":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to look for in the highlighted passage.","title":"Quote"},"sort":{"anyOf":[{"enum":["created","updated","group","id","user"],"type":"string"},{"type":"null"}],"default":"updated","description":"Sort field: created, updated, group, id or user.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc or desc.","title":"Order"},"limit":{"anyOf":[{"maximum":200,"minimum":0,"type":"integer"},{"type":"null"}],"default":20,"description":"How many annotations to return (0 to 200).","title":"Limit"},"offset":{"anyOf":[{"maximum":9800,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip (maximum 9800); use search_after for deep paging.","title":"Offset"},"search_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start after this sort-field value (ISO 8601 time for created or updated sorting).","title":"Search After"}},"title":"search_annotationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_annotation":{"post":{"operationId":"get_annotation","summary":"Get one annotation by id with its comment text, tags, URL, group and document title. Use for \"Show Hypothesis annotation","description":"Get one annotation by id with its comment text, tags, URL, group and document title. Use for \"Show Hypothesis annotation 'abc123XYZ'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"annotation_id":{"description":"Annotation id, as returned by search_annotations.","maxLength":200,"title":"Annotation Id","type":"string"}},"required":["annotation_id"],"title":"get_annotationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_group":{"post":{"operationId":"get_group","summary":"Get one group: name, type, whether it is scoped to certain URLs, and its page link. Use for \"Give me details of my Hypot","description":"Get one group: name, type, whether it is scoped to certain URLs, and its page link. Use for \"Give me details of my Hypothesis group '8JmD3iz1'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Group identifier (short id such as '8JmD3iz1', from list_my_groups); the public group is '__world__'.","maxLength":200,"title":"Group Id","type":"string"}},"required":["group_id"],"title":"get_groupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_groups":{"post":{"operationId":"list_groups","summary":"List groups visible to the account, optionally limited to those applying to a document URL. Use for \"Which Hypothesis gr","description":"List groups visible to the account, optionally limited to those applying to a document URL. Use for \"Which Hypothesis groups apply to https://example.com/article\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"document_uri":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only public groups that apply to this document URL.","title":"Document Uri"},"authority":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"hypothes.is","description":"Authority to list groups for, default hypothes.is.","title":"Authority"}},"title":"list_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_group_members":{"post":{"operationId":"list_group_members","summary":"List the members of a group (user id, display name, roles, join date), oldest member first. Use for \"Who is in my Hypoth","description":"List the members of a group (user id, display name, roles, join date), oldest member first. Use for \"Who is in my Hypothesis group '8JmD3iz1'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Group identifier (short id such as '8JmD3iz1', from list_my_groups); the public group is '__world__'.","maxLength":200,"title":"Group Id","type":"string"},"page_number":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Members per page (1 to 100).","title":"Page Size"}},"required":["group_id"],"title":"list_group_membersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_group_annotations":{"post":{"operationId":"list_group_annotations","summary":"List annotations made in a group, newest first, with cursor paging by date. Use for \"Show the latest annotations in my H","description":"List annotations made in a group, newest first, with cursor paging by date. Use for \"Show the latest annotations in my Hypothesis group '8JmD3iz1'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Group identifier (short id such as '8JmD3iz1', from list_my_groups); the public group is '__world__'.","maxLength":200,"title":"Group Id","type":"string"},"page_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only annotations older than this ISO 8601 date-time.","title":"Page After"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Annotations per page (1 to 100).","title":"Page Size"}},"required":["group_id"],"title":"list_group_annotationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}