Skip to content

api.md

Latest commit

 

History

History
214 lines (151 loc) · 4.91 KB

api.md

File metadata and controls

214 lines (151 loc) · 4.91 KB

API Reference

This document covers the Workbench-facing API surface. All endpoints are under /api.

Access Code

When SCNU_ACCESS_CODE is set, all /api/* routes require the access cookie except:

  • GET /api/health
  • POST /api/public/precheck/docx
  • POST /api/public/precheck/text
  • POST /api/public/exports/docx
  • POST /api/public/export-jobs/docx
  • GET /api/public/export-jobs/{id}
  • POST /api/public/export-jobs/{id}/cancel
  • POST /api/public/export-jobs/{id}/retry
  • GET /api/public/exports/{id}/download
  • GET /api/public/exports/{id}/report
  • GET /api/access-code/status
  • POST /api/access-code/verify

Public Quick Export

POST /api/public/precheck/docx

Multipart fields:

  • file: .docx, max 20 MB
  • privacy_accepted: must be true
  • turnstile_token: required in production

Returns PrecheckResponse with export_token and expires_at.

POST /api/public/precheck/text

JSON request:

{
  "text": "已有论文正文",
  "privacy_accepted": true,
  "turnstile_token": "..."
}

Text input is limited to 80,000 characters. The endpoint is for existing thesis text precheck only.

POST /api/public/exports/docx

JSON request:

{
  "thesis": {},
  "export_token": "..."
}

Returns a retained export with download_url, report_url, and expires_at. Public exports are kept for 30 minutes.

This synchronous endpoint is retained for compatibility. The public UI uses the Job endpoints below.

POST /api/public/export-jobs/docx

JSON request:

{
  "thesis": {},
  "export_token": "..."
}

Creates a background export job and returns:

{
  "job_id": "job_...",
  "export_id": "pub_...",
  "status": "running",
  "progress": 5,
  "message": "导出任务已创建。",
  "download_url": null,
  "report_url": null,
  "expires_at": "2026-04-21T12:30:00",
  "error_code": null
}

Job status values:

  • running
  • done
  • failed
  • canceled

GET /api/public/export-jobs/{id}

Returns the latest persisted job status. When status=done, download_url and report_url are available.

POST /api/public/export-jobs/{id}/cancel

Requests cancellation and returns the persisted job status. Cancellation is cooperative: if the export has already completed, the completed state is returned.

POST /api/public/export-jobs/{id}/retry

Retries a failed or canceled job with the original request payload while the original export_token remains valid.

GET /api/access-code/status

Returns:

{
  "required": true,
  "verified": false
}

POST /api/access-code/verify

Request:

{
  "access_code": "..."
}

On success, the backend sets an HttpOnly cookie and returns verified=true.

Projects

POST /api/projects

Creates an SCNU undergraduate project. The server defaults are:

  • school=scnu
  • degree_level=undergraduate
  • template_profile=scnu-undergraduate
  • rule_set_id=scnu-undergraduate-2025
  • privacy_mode=local_only
  • remote_provider_allowed=false

Request fields:

  • title
  • department
  • major
  • advisor
  • student_name
  • student_id
  • writing_stage: topic, proposal, draft, revision, final_check
  • privacy_mode: local_only, remote_allowed
  • remote_provider_allowed

PATCH /api/projects/{id}

Updates project metadata and privacy settings. If privacy_mode=local_only, the server forces remote_provider_allowed=false.

Provider Configs

GET /api/providers

Returns Provider metadata only. API keys are never included.

GET /api/provider-configs

Returns saved Provider configs with:

  • provider
  • model
  • base_url
  • allow_local
  • has_api_key
  • verification_status
  • verification_message

Raw API keys are never returned.

POST /api/provider-configs

Stores a Provider config and seals api_key server-side.

Remote Providers reject private, loopback, link-local, reserved, and multicast base_url targets. Ollama can use local loopback/private addresses only when allow_local=true; link-local, reserved, and multicast targets remain blocked.

POST /api/provider-configs/{id}/verify

Runs metadata verification only. It does not call a remote LLM and does not send论文正文.

  • Remote Providers require a model and saved API key.
  • Ollama may perform a short local /api/tags probe when a base URL is configured.

DELETE /api/provider-configs/{id}

Soft-deletes the Provider config.

Existing Workbench APIs

  • POST /api/projects/{id}/files
  • GET /api/projects/{id}/files
  • POST /api/projects/{id}/parse-jobs
  • GET /api/jobs/{id}
  • GET /api/jobs/{id}/events
  • GET /api/jobs/{id}/events/stream
  • GET /api/projects/{id}/versions
  • GET /api/projects/{id}/issues
  • GET /api/projects/{id}/proposals
  • POST /api/proposals/{id}/accept
  • POST /api/proposals/{id}/reject
  • POST /api/proposals/{id}/stash
  • POST /api/projects/{id}/exports
  • GET /api/projects/{id}/exports
  • GET /api/exports/{id}/download