the_order/docs/legal/document-management/api-reference.md

# Legal Documents Service API Documentation

## Base URL
```
http://localhost:4005
```

## Authentication
All endpoints require JWT authentication via `Authorization: Bearer <token>` header.

## Endpoints

### Documents

#### Create Document
```http
POST /documents
Content-Type: application/json

{
  "title": "Document Title",
  "type": "legal",
  "content": "Document content",
  "matter_id": "optional-matter-id"
}
```

#### Get Document
```http
GET /documents/:id
```

#### List Documents
```http
GET /documents?type=legal&matter_id=xxx&limit=100&offset=0
```

#### Update Document
```http
PATCH /documents/:id
Content-Type: application/json

{
  "title": "Updated Title",
  "content": "Updated content"
}
```

#### Checkout Document
```http
POST /documents/:id/checkout
Content-Type: application/json

{
  "duration_hours": 24,
  "notes": "Editing document"
}
```

#### Checkin Document
```http
POST /documents/:id/checkin
```

### Versions

#### List Versions
```http
GET /documents/:id/versions
```

#### Get Version
```http
GET /documents/:id/versions/:version
```

#### Compare Versions
```http
GET /documents/:id/versions/:v1/compare/:v2
```

#### Restore Version
```http
POST /documents/:id/versions/:version/restore
Content-Type: application/json

{
  "change_summary": "Restored from version 1"
}
```

### Templates

#### Create Template
```http
POST /templates
Content-Type: application/json

{
  "name": "Contract Template",
  "template_content": "Contract between {{party1}} and {{party2}}",
  "category": "contract"
}
```

#### Render Template
```http
POST /templates/:id/render
Content-Type: application/json

{
  "variables": {
    "party1": "Acme Corp",
    "party2": "Beta Inc"
  }
}
```

### Matters

#### Create Matter
```http
POST /matters
Content-Type: application/json

{
  "matter_number": "MAT-2024-001",
  "title": "Legal Matter Title",
  "description": "Matter description"
}
```

#### Link Document to Matter
```http
POST /matters/:matter_id/documents/:document_id
Content-Type: application/json

{
  "relationship_type": "primary_evidence"
}
```

### Assembly

#### Generate from Template
```http
POST /assembly/generate
Content-Type: application/json

{
  "template_id": "template-id",
  "variables": { "name": "John" },
  "title": "Generated Document",
  "save_document": true
}
```

### Workflows

#### Create Workflow
```http
POST /workflows
Content-Type: application/json

{
  "document_id": "doc-id",
  "workflow_type": "approval",
  "steps": [
    {
      "step_number": 1,
      "step_type": "approval",
      "assigned_to": "user-id"
    }
  ]
}
```

### Filings

#### Create Filing
```http
POST /filings
Content-Type: application/json

{
  "document_id": "doc-id",
  "matter_id": "matter-id",
  "court_name": "Supreme Court",
  "filing_type": "motion"
}
```

### Search

#### Search Documents
```http
POST /search
Content-Type: application/json

{
  "query": "search terms",
  "filters": {
    "type": "legal"
  }
}
```

## Error Responses

All errors follow this format:
```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

Common error codes:
- `NOT_FOUND` - Resource not found
- `UNAUTHORIZED` - Authentication required
- `FORBIDDEN` - Insufficient permissions
- `VALIDATION_ERROR` - Invalid input
- `CONFLICT` - Resource conflict (e.g., document checked out)