Skip to content

rest.md

Latest commit

 

History

History
158 lines (113 loc) · 3 KB

rest.md

File metadata and controls

158 lines (113 loc) · 3 KB
Raw

DocForge REST API Reference

Base URL: {origin}/api/v1 (default local: http://127.0.0.1:8787/api/v1)

OpenAPI: {origin}/api/docs

Discovery

Agent manifest

GET /api/v1/agent-manifest
GET /.well-known/docforge.json

Returns registration URLs, MCP tools, chunking defaults, documentation links, and example curl commands.

Health

GET /api/v1/health
{ "status": "ok", "version": "1.0.0", "timestamp": "…" }

Agent registration

Register (self-service)

POST /api/v1/agents/register
Content-Type: application/json

{
  "name": "my-rag-agent",
  "description": "Optional",
  "capabilities": ["ingest", "chunk", "convert"],
  "webhook_url": "https://example.com/hook",
  "metadata": { "team": "platform" }
}

201 response includes api_key, cursor_config, mcp_env — store immediately.

409 if agent name already exists.

List agents

GET /api/v1/agents

Public metadata only (no API keys).

Current agent

GET /api/v1/agents/me
X-DocForge-Key: df_YOUR_KEY

Document ingest

All ingest endpoints accept multipart/form-data. Max upload size: 50 MB (configurable via DOCFORGE_MAX_UPLOAD_MB).

Optional auth header: X-DocForge-Key: df_…

Full pipeline (recommended)

POST /api/v1/ingest
X-DocForge-Key: df_YOUR_KEY
Content-Type: multipart/form-data

file=@report.pdf
strategy=headings
max_tokens=512
overlap_tokens=64
min_heading_level=1
max_heading_level=3
include_heading_path=true
token_model=cl100k_base

Response fields:

Field Type Description
document_id UUID Stable document identifier
markdown string Clean normalized Markdown
chunks array Chunk records with token estimates
chunk_count int Number of chunks
total_chunk_tokens int Sum of chunk token estimates
token_estimate int Full document token count
config object Chunk config used

Convert only

POST /api/v1/convert
Content-Type: multipart/form-data

file=@page.html

Chunk Markdown

POST /api/v1/chunk
Content-Type: multipart/form-data

markdown=# Title

Body text…
strategy=size
max_tokens=512
overlap_tokens=64

Authentication

Header Format
X-DocForge-Key df_<urlsafe-secret>

Obtain via self-registration. Optional for ingest endpoints; required for /agents/me.

Error codes

Code Meaning
400 Missing filename or invalid input
401 Invalid API key
409 Agent name conflict
413 File too large
415 Unsupported format

curl examples

Register:

curl -sS -X POST 'http://127.0.0.1:8787/api/v1/agents/register' \
  -H 'content-type: application/json' \
  -d '{"name":"demo-bot","capabilities":["ingest"]}'

Ingest:

curl -sS -X POST 'http://127.0.0.1:8787/api/v1/ingest' \
  -H 'X-DocForge-Key: df_YOUR_KEY' \
  -F 'file=@document.pdf' \
  -F 'strategy=headings' \
  -F 'max_tokens=512'