API reference

REST API endpoints for programmatic access to Rebuttr.

Base URL

All endpoints are relative to http://localhost:3001

Overview

Rebuttr exposes a REST API for interacting with papers, comments, and AI features. The server runs on port 3001 by default.

Configuration

GET /config

Get the current configuration settings.

                    Response
                

{
  "model": "github-copilot/gpt-5-mini",
  "agent": "general",
  "variant": "high",
  "available_models": [...],
  "available_agents": [...],
  "available_variants": [...]
}
                

POST /config

Update configuration settings.

Field	Type	Description
`model`	string	AI model identifier
`agent`	string	Agent type (plan, build, explore, general)
`variant`	string	Reasoning effort level

Papers

GET /api/papers

List all papers in the database.

                    Response
                

{
  "papers": [
    {
      "id": "2ad87606",
      "title": "Two-million-year-old microbial communities...",
      "created_at": "2025-01-20T12:00:00Z",
      "status": "ready"
    }
  ]
}
                

GET /api/papers/incomplete

List papers that are still being processed.

DELETE /api/papers/:id

Delete a paper and all its associated data.

Parameter	Type	Description
`id` (required)	string	Paper ID

Comments

GET /db/comments

Load all comments for a paper.

Query Parameter	Type	Description
`paper` (required)	string	Paper ID

POST /db/comments

Save all comments for a paper.

Field	Type	Description
`paperId` (required)	string	Paper ID
`comments` (required)	array	Array of comment objects

Expert Discussions

GET /db/experts

Load expert discussions for a paper.

Query Parameter	Type	Description
`paper` (required)	string	Paper ID

POST /db/expert

Save an expert discussion for a comment.

Field	Type	Description
`paperId` (required)	string	Paper ID
`commentId` (required)	string	Comment ID
`discussion` (required)	object	Expert discussion data

Export

POST /papers/:id/export/ai-rebuttal

Generate an AI-powered rebuttal letter as a Word document.

Parameter	Type	Description
`id` (required)	string	Paper ID

Response

Returns a .docx file download.

App State

GET /db/state/:key

Load saved application state by key.

POST /db/state

Save application state.

Field	Type	Description
`key` (required)	string	State key identifier
`value` (required)	any	State data to save

Error Handling

All endpoints return JSON error responses:

                    Error Response
                
{
  "error": "Error message describing what went wrong"
}

HTTP status codes:

200 - Success
400 - Bad request (missing/invalid parameters)
404 - Resource not found
500 - Server error

Authentication

The Rebuttr API is designed for local use and does not require authentication. Do not expose the server to the public internet.

Next Steps

JSON format - Data structure details
Configuration - Server settings
Troubleshooting - Common issues