Skip to content

api-reference.md

Latest commit

 

History

History
437 lines (357 loc) · 7.41 KB

api-reference.md

File metadata and controls

437 lines (357 loc) · 7.41 KB

API Reference

The Verbweaver API provides programmatic access to all features of the platform. This reference covers the REST API endpoints available at /api/v1.

Base URL

http://localhost:8000/api/v1

Authentication

Most endpoints require authentication using JWT tokens.

Obtain Token

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=yourpassword

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer"
}

Using Token

Include the token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Endpoints

Authentication

Register User

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

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John Doe"
}

Login

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

Refresh Token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Get Current User

GET /api/v1/auth/me
Authorization: Bearer {token}

Projects

List Projects

GET /api/v1/projects
Authorization: Bearer {token}

Response:

[
  {
    "id": "proj_123",
    "name": "My Novel",
    "description": "A science fiction novel",
    "gitRepository": {
      "type": "local",
      "path": "./git-repos/my-novel"
    },
    "created": "2024-01-01T00:00:00Z",
    "modified": "2024-01-02T00:00:00Z"
  }
]

Create Project

POST /api/v1/projects
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My New Project",
  "description": "Project description",
  "gitRepository": {
    "type": "local"
  }
}

Get Project

GET /api/v1/projects/{project_id}
Authorization: Bearer {token}

Update Project

PUT /api/v1/projects/{project_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description"
}

Delete Project

DELETE /api/v1/projects/{project_id}
Authorization: Bearer {token}

Graph Operations

Get Graph

GET /api/v1/projects/{project_id}/graph
Authorization: Bearer {token}

Response:

{
  "nodes": [
    {
      "id": "node_1",
      "type": "document",
      "title": "Chapter 1",
      "metadata": {...},
      "position": {"x": 100, "y": 100}
    }
  ],
  "edges": [
    {
      "id": "edge_1",
      "source": "node_1",
      "target": "node_2",
      "type": "reference"
    }
  ]
}

Create Node

POST /api/v1/projects/{project_id}/graph/nodes
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "document",
  "title": "New Node",
  "content": "# New Node\n\nContent here...",
  "metadata": {
    "tags": ["important"]
  }
}

Update Node

PUT /api/v1/projects/{project_id}/graph/nodes/{node_id}
Authorization: Bearer {token}

Delete Node

DELETE /api/v1/projects/{project_id}/graph/nodes/{node_id}
Authorization: Bearer {token}

Create Edge

POST /api/v1/projects/{project_id}/graph/edges
Authorization: Bearer {token}
Content-Type: application/json

{
  "source": "node_1",
  "target": "node_2",
  "type": "reference",
  "label": "relates to"
}

Tasks

List Tasks

GET /api/v1/projects/{project_id}/tasks
Authorization: Bearer {token}

Create Task

POST /api/v1/projects/{project_id}/tasks
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Write Chapter 1",
  "description": "Complete the first draft",
  "status": "todo",
  "priority": "high",
  "dueDate": "2024-02-01T00:00:00Z"
}

Update Task

PUT /api/v1/projects/{project_id}/tasks/{task_id}
Authorization: Bearer {token}

Move Task

PATCH /api/v1/projects/{project_id}/tasks/{task_id}/move
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "in_progress"
}

Editor

Get File

GET /api/v1/projects/{project_id}/files/{file_path}
Authorization: Bearer {token}

Save File

PUT /api/v1/projects/{project_id}/files/{file_path}
Authorization: Bearer {token}
Content-Type: application/json

{
  "content": "File content here..."
}

Delete File

DELETE /api/v1/projects/{project_id}/files/{file_path}
Authorization: Bearer {token}

Version Control

Get Commits

GET /api/v1/projects/{project_id}/git/commits
Authorization: Bearer {token}

Create Commit

POST /api/v1/projects/{project_id}/git/commit
Authorization: Bearer {token}
Content-Type: application/json

{
  "message": "Updated chapter 1",
  "files": ["chapter1.md"]
}

Get Diff

GET /api/v1/projects/{project_id}/git/diff?from={commit1}&to={commit2}
Authorization: Bearer {token}

Compiler

Export Project

POST /api/v1/projects/{project_id}/compiler/compile
Authorization: Bearer {token}
Content-Type: application/json

{
  "format": "pdf",
  "nodes": ["node_1", "node_2"],
  "template": "default",
  "options": {
    "includeMetadata": false,
    "pageSize": "A4"
  }
}

Response:

{
  "exportId": "exp_123",
  "status": "processing",
  "downloadUrl": null
}

Check Export Status

GET /api/v1/projects/{project_id}/compiler/status/{export_id}
Authorization: Bearer {token}

WebSocket Events

Connect to receive real-time updates:

const ws = new WebSocket('ws://localhost:8000/ws/{project_id}?token={token}');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.data);
};

Event Types

  • file-changed: File was modified
  • node-created: New node added to graph
  • node-updated: Node properties changed
  • edge-created: New edge added
  • task-moved: Task status changed
  • user-joined: User joined project
  • user-left: User left project

Rate Limiting

API requests are limited to:

  • 60 requests per minute for authenticated users
  • 20 requests per minute for unauthenticated users

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Error Responses

{
  "detail": "Error message",
  "code": "ERROR_CODE",
  "field": "field_name" // For validation errors
}

Common error codes:

  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 422: Validation Error
  • 429: Too Many Requests
  • 500: Internal Server Error

SDK Examples

Python

import requests

class VerbweaverAPI:
    def __init__(self, base_url, token=None):
        self.base_url = base_url
        self.token = token
        
    def get_projects(self):
        headers = {"Authorization": f"Bearer {self.token}"}
        response = requests.get(f"{self.base_url}/projects", headers=headers)
        return response.json()

JavaScript

class VerbweaverAPI {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
  }
  
  async getProjects() {
    const response = await fetch(`${this.baseUrl}/projects`, {
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }
}

OpenAPI Specification

The OpenAPI spec and docs are available at:

http://localhost:8000/api/v1/openapi.json
http://localhost:8000/api/v1/docs