API Editor Service #

The API Editor Service is an LLM-driven collaborative OpenAPI schema creation and editing backend.

Users interact through a chat interface to describe or refine an API. The LLM generates and iterates on a versioned OpenAPI document. Multiple clients can edit simultaneously using an optimistic-concurrency RFC 6902 patch merge model.

Concepts #

The service is organized around four core concepts:

Document Versioning Model #

Every mutation produces a new monotonically increasing version number. The history endpoint exposes can_undo and can_redo flags along with the full version list.

Collaborative Merge #

When multiple clients are editing, they submit RFC 6902 patch operations via /documents/merge. The server performs an optimistic rebase:

• Client provides base_version — the version the edits were authored against.
• If the server is ahead, a rebase is attempted automatically.
• The response includes rebase_applied, conflict_paths, and the resulting new version.

LLM Lock #

When the LLM is generating a document update, the project is locked. The EditorStatusResponse exposes is_locked_for_llm. Clients should poll or check this before submitting manual edits.

Sending a message with generate_openapi_draft: true (the default) will trigger LLM-driven document generation and produce a new version atomically with the assistant reply.

API Reference #

Health #

Projects #

Create project body:

{
  "name": "My API",
  "description": "Optional description",
  "initial_openapi_document": { ... }
}

Documents #

All document routes are scoped under /v1/projects/{project_id}/documents.

Save document body:

{
  "base_version": 3,
  "spec": {
    "openapi": "3.1.0",
    "info": { "title": "My API", "version": "1.0.0" },
    "paths": {}
  }
}

Merge patch body:

{
  "base_version": 3,
  "actor_label": "Alice",
  "operations": [
    { "op": "add", "path": "/paths/~1users", "value": { ... } }
  ]
}

Conversations #

Send message body:

{
  "content": "Add a POST /users endpoint that creates a user",
  "generate_openapi_draft": true,
  "expected_document_version": 3
}

expected_document_version acts as an optimistic guard — the LLM will be told the current version to base its update on.

Collaboration #

Clients should send heartbeats regularly to stay visible. Sessions expire automatically if heartbeats stop.