canonical: https://jentic.com/apis/bibsonomy.org/bibsonomy # BibSonomy REST API BibSonomy is a social bookmarking and academic publication sharing system run by the University of Kassel and partners. The REST API gives programmatic access to users, posts (which can be either bookmarks or BibTeX publications), tags, concepts (controlled hierarchies of tags), groups, persons, and document attachments. Authentication uses HTTP Basic with the BibSonomy username and API key generated in the user settings. The 46 endpoints are organised around the user as the primary resource and let agents publish references, share reading lists, and collaborate inside research groups. ## For AI agents Manage BibSonomy bookmarks, BibTeX publications, tags, concepts, groups, and document attachments for academic reference sharing. ## Scope Does not handle full-text search across the academic literature, citation graphs, or DOI resolution - use for personal and group reference library management only. ## Capabilities - Publish BibTeX publications and bookmarks to a BibSonomy user account - Tag publications with controlled vocabulary concepts for organised reading lists - Manage concepts (tag hierarchies) used to structure a personal library - Attach PDF documents and supplementary files to a BibSonomy post - Add and remove friends and group memberships for collaborative reference sharing - Browse posts by user, group, tag, or shared clipboard - Look up persons across the BibSonomy social graph ## Use cases ### Reference Manager Sync Sync a researcher's BibTeX library between a desktop reference manager and BibSonomy so collaborators can read and cite the shared library through the web interface. POST `/users/{username}/posts` publishes a publication; GET `/users/{username}/posts` retrieves the full library; PUT updates an entry. Document attachments under /documents/ keep PDFs alongside the metadata. Example prompt: POST a new BibTeX entry to `/users/researcher42/posts` with title, authors, year, and an attached PDF. ### Research Group Reading List Run a shared reading list inside a BibSonomy group so every member sees newly added papers and can comment via tags. GET `/groups/{groupname}` returns the group profile, and posts are surfaced through the group's user-tagged publications. The clipboard endpoint helps a curator stage papers before publishing them to the group. Example prompt: List the members of group 'lab-deep-learning' and surface every paper they have tagged with 'transformers' in the last 30 days. ### Tag-Based Discovery Feed Build a discovery feed that surfaces new bookmarks and publications from across BibSonomy by tag, similar to a topic tracker. Iterate user posts with a tag filter and present new items to the reader. This is useful for staying on top of an evolving research area without subscribing to individual users. Example prompt: Iterate `/users/{username}/posts` for a curated set of users and pull every post tagged 'graph-neural-networks' added in the last week. ### AI Agent Reference Curator An AI agent helping a PhD student curate references can publish new papers to BibSonomy and tag them appropriately, reading existing posts to avoid duplicates. Through Jentic, the agent searches by intent ('add a BibTeX entry to my library'), loads the schema, and executes - Jentic supplies the basic-auth credentials so the agent never sees the username and password pair. Example prompt: Search Jentic for 'create a BibSonomy post', execute POST `/users/researcher42/posts`, and tag the resulting entry with 'literature-review'. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/users/{username}/posts` | List posts for a user | | POST | `/users/{username}/posts` | Create a post | | PUT | `/users/{username}/posts/{resourceHash}` | Update a post | | POST | `/users/{username}/posts/{resourceHash}/documents/` | Add a document to a post | | GET | `/users/{username}/concepts` | List concepts for a user | | GET | `/groups` | List all groups | ## Key resources - **Users** — Create, retrieve, update, and delete BibSonomy user profiles - **Posts** — Manage publications and bookmarks owned by a user - **Documents** — Attach and rename document files on a post - **Concepts** — Hierarchical tags used to structure a personal library - **Groups** — Manage research groups and their members - **Friends** — Manage friend connections between users ## Why Jentic - **Setup:** Wiring the BibSonomy REST API by hand means sending your username and API key as HTTP Basic auth on every call and building each user-scoped post path yourself. Through Jentic you install once, import BibSonomy from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** BibSonomy puts the username in the URL path (`/users/{username}/posts/...`), so a rule can pin your agent to one user's library: it can read and create posts under that user and nothing else. You choose the operations it may call, so post updates or document uploads are not included unless you add them. - **Credential handling:** Your BibSonomy username and API key are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a BibSonomy post' or 'list a user's references', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Mendeley API** — Mendeley is a commercial reference manager API operated by Elsevier with broader catalogue integrations. - **Crossref API** — Crossref resolves DOI metadata that can be published as BibTeX entries into BibSonomy. - **Figshare API** — Figshare hosts the underlying datasets and PDFs that can be linked from BibSonomy posts. ## FAQ ### What authentication does the BibSonomy API use? BibSonomy uses HTTP Basic authentication with your BibSonomy username and API key (the API key is generated in user settings, separate from the web password). Through Jentic, the basic-auth pair is stored encrypted in the your Jentic One instance and injected at execution time so the agent never sees the API key. ### Can I publish a BibTeX entry to my BibSonomy library? Yes. POST `/users/{username}/posts` accepts a publication post body that includes the BibTeX fields (title, author, year, and so on) plus tags. The response includes a resourceHash that identifies the new post for later updates or document attachments. ### How do I attach a PDF to a BibSonomy post? After creating the post, POST the file to `/users/{username}/posts/{resourceHash}/documents/.` The document then appears alongside the post and can be renamed via PUT or removed via DELETE on the same path with the document's filename. ### How do I create a BibSonomy post through Jentic? Search Jentic for 'create a BibSonomy post', load `/users/{username}/posts` (POST), and execute with the BibTeX entry body. With the SDK: pip install jentic, then SearchRequest, LoadRequest, ExecutionRequest in an async flow - Jentic injects the basic-auth credentials. ### Is the BibSonomy API free? Yes - BibSonomy is run as a free academic service by the University of Kassel and partners. Use it within fair-use rate limits, which are not declared in the OpenAPI spec but enforced server-side. ### Can I limit what my agent is allowed to do with the BibSonomy API? Yes. Jentic One is self-hosted by you, so your own rules decide which BibSonomy operations and credentials the agent may use. Because BibSonomy puts the username in the URL path (`/users/{username}/posts`), you can pin the agent to one user's library so it only reads and creates posts under that account and nothing else. You choose the operations it may call, so post updates via PUT or document uploads to /documents/ are excluded unless you explicitly add them.