CODITECT DMS API Reference

Complete REST API reference for the CODITECT Document Management System.

Overview

The CODITECT DMS API provides:

Semantic Search: AI-powered document search with vector embeddings
Hybrid Search: Combined vector + keyword search with RRF fusion
GraphRAG: Graph-based relationship traversal
Document Management: Full CRUD with intelligent processing
Analytics: Real-time metrics and usage tracking
Multi-Tenancy: Complete tenant isolation with RBAC

Base URLs:

Production: https://dms-api.coditect.ai/api/v1
Staging: https://dms-api-staging.coditect.ai/api/v1
Local: http://localhost:8000/api/v1

Authentication

JWT Token Authentication

Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Token Expiration: 24 hours Refresh: Use /auth/refresh endpoint before expiration

API Key Authentication

For programmatic access, use API keys:

X-API-Key: dms_prod_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key Format: dms_{env}_{type}_{32-char-secret}

env: prod, staging, dev
type: sk (secret key), pk (publishable key)

Security Notes:

Never expose secret keys in client-side code
Rotate keys periodically
Use scoped keys with minimum required permissions

Rate Limiting

Tier	Requests/Min	Searches/Min	Documents/Hour
Free	100	50	10
Pro	1,000	500	100
Enterprise	10,000	5,000	1,000

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1703750400

Error Handling

All errors follow RFC 7807 Problem Details format:

{
  "type": "https://api.coditect.ai/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "query",
      "message": "Query must be at least 1 character"
    }
  ]
}

Common Error Codes

Status	Error Type	Description
400	validation_error	Invalid request parameters
401	unauthorized	Missing or invalid auth
403	forbidden	Insufficient permissions
404	not_found	Resource not found
409	conflict	Resource already exists
413	payload_too_large	File exceeds size limit
429	rate_limited	Too many requests
500	internal_error	Server error
503	service_unavailable	Service temporarily down

Endpoints

Health Checks

GET /health

Basic health check for load balancers.

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-28T12:00:00Z"
}

GET /health/ready

Detailed readiness check (Kubernetes readiness probe).

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-12-28T12:00:00Z",
  "components": {
    "database": "healthy",
    "redis": "healthy"
  }
}

GET /health/live

Liveness probe (Kubernetes liveness probe).

Response:

{
  "status": "alive",
  "timestamp": "2025-12-28T12:00:00Z"
}

Search

POST /search

Execute semantic search across documents.

Request:

{
  "query": "How do I implement authentication?",
  "mode": "hybrid",
  "top_k": 10,
  "min_score": 0.3,
  "include_content": true,
  "include_metadata": true,
  "expand_context": false
}

Parameters:

Field	Type	Default	Description
query	string	required	Search query (1-2000 chars)
mode	string	hybrid	vector, keyword, hybrid, graphrag
top_k	integer	10	Max results (1-100)
min_score	number	0.3	Minimum relevance score (0-1)
include_content	boolean	true	Include chunk content
include_metadata	boolean	true	Include metadata
expand_context	boolean	false	Include surrounding chunks
context_chunks	integer	1	Number of context chunks (0-5)

Response:

{
  "query": "How do I implement authentication?",
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440001",
      "doc_id": "550e8400-e29b-41d4-a716-446655440000",
      "score": 0.92,
      "content": "## Authentication\n\nTo implement JWT authentication...",
      "section_title": "Authentication",
      "document_title": "Security Guide",
      "highlight": "To implement JWT <em>authentication</em>...",
      "metadata": {
        "document_type": "guide",
        "keywords": ["jwt", "security", "auth"]
      }
    }
  ],
  "total_results": 15,
  "search_time_ms": 45,
  "mode": "hybrid",
  "model_name": "text-embedding-3-small"
}

POST /search/graphrag

Execute GraphRAG traversal from a seed chunk.

Request:

{
  "seed_chunk_id": "550e8400-e29b-41d4-a716-446655440001",
  "max_depth": 2,
  "max_nodes": 10,
  "relationship_types": ["sequential", "semantic"],
  "min_weight": 0.5
}

Response:

{
  "seed_chunk": {
    "chunk_id": "550e8400-e29b-41d4-a716-446655440001",
    "doc_id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Authentication implementation...",
    "section_title": "Authentication",
    "sequence_num": 5
  },
  "related_chunks": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440002",
      "doc_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "JWT token verification...",
      "section_title": "JWT Tokens",
      "sequence_num": 6
    }
  ],
  "relationships": [
    {
      "source_id": "550e8400-e29b-41d4-a716-446655440001",
      "target_id": "550e8400-e29b-41d4-a716-446655440002",
      "relationship_type": "sequential",
      "weight": 0.95,
      "confidence": 1.0
    }
  ],
  "total_score": 2.85,
  "traversal_depth": 1,
  "retrieval_time_ms": 23
}

GET /search/suggest

Get autocomplete suggestions.

Parameters:

query (string, required): Partial query
limit (integer, default 5): Max suggestions (1-20)

Response:

{
  "query": "auth",
  "suggestions": [
    "authentication guide",
    "authorization patterns",
    "auth middleware",
    "API authentication",
    "JWT auth"
  ]
}

Documents

GET /documents

List documents with pagination and filtering.

Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page (1-100)
status	string	-	Filter by status
document_type	string	-	Filter by type
search	string	-	Search in title/filename

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "security-guide.md",
      "filepath": "/documents/security-guide.md",
      "mime_type": "text/markdown",
      "file_size": 15420,
      "status": "completed",
      "document_type": "guide",
      "title": "Security Guide",
      "chunk_count": 24,
      "created_at": "2025-12-28T10:00:00Z",
      "updated_at": "2025-12-28T10:15:00Z"
    }
  ],
  "total": 1250,
  "page": 1,
  "page_size": 20,
  "total_pages": 63
}

POST /documents

Create a new document.

Request:

{
  "filename": "new-guide.md",
  "content": "# New Guide\n\nThis is a new guide...",
  "content_type": "text/markdown",
  "title": "New Guide",
  "document_type": "guide",
  "keywords": ["new", "guide"],
  "tags": ["documentation"]
}

Response: Document object with status: "pending"

POST /documents/upload

Upload a document file.

Request: multipart/form-data with file field

Supported Formats:

Markdown (.md)
Text (.txt)
PDF (.pdf)
Word (.docx)

Max File Size: 50 MB

GET /documents/{doc_id}

Get document by ID.

Response: Full document object with metadata

PUT /documents/{doc_id}

Update document metadata.

Request:

{
  "title": "Updated Title",
  "summary": "Updated summary",
  "document_type": "reference",
  "keywords": ["updated", "reference"],
  "tags": ["v2"]
}

DELETE /documents/{doc_id}

Delete document and all associated data.

Response: 204 No Content

GET /documents/{doc_id}/chunks

Get document chunks with pagination.

Response:

{
  "doc_id": "550e8400-e29b-41d4-a716-446655440000",
  "chunks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "doc_id": "550e8400-e29b-41d4-a716-446655440000",
      "sequence_num": 0,
      "content": "# Introduction\n\nThis guide covers...",
      "start_offset": 0,
      "end_offset": 512,
      "token_count": 128,
      "word_count": 95,
      "section_title": "Introduction",
      "has_embedding": true
    }
  ],
  "total_chunks": 24
}

POST /documents/{doc_id}/reprocess

Trigger document reprocessing.

Response:

{
  "doc_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "progress": 0.0,
  "current_step": "Queued for reprocessing"
}

Analytics

GET /analytics/dashboard

Get aggregated dashboard metrics.

Response:

{
  "timestamp": "2025-12-28T12:00:00Z",
  "document_metrics": {
    "total_documents": 1250,
    "documents_by_type": {
      "reference": 450,
      "guide": 320,
      "adr": 85
    },
    "documents_by_status": {
      "completed": 1180,
      "processing": 45,
      "pending": 15,
      "failed": 10
    },
    "total_chunks": 28500,
    "total_embeddings": 28500,
    "avg_chunks_per_doc": 22.8,
    "total_storage_bytes": 524288000
  },
  "search_metrics": {
    "total_searches": 15420,
    "avg_latency_ms": 85.5,
    "p95_latency_ms": 145.0,
    "p99_latency_ms": 220.0,
    "searches_by_mode": {
      "hybrid": 12500,
      "vector": 2100
    },
    "cache_hit_rate": 0.72
  },
  "processing_metrics": {
    "total_jobs": 5840,
    "completed_jobs": 5680,
    "failed_jobs": 95,
    "pending_jobs": 65
  },
  "cost_metrics": {
    "total_embedding_cost_usd": 45.82,
    "total_tokens_used": 2291000,
    "avg_cost_per_document": 0.0367
  }
}

POST /analytics/metrics

Query time-series metrics.

Request:

{
  "metric_types": ["searches_performed", "documents_uploaded"],
  "start_time": "2025-12-21T00:00:00Z",
  "end_time": "2025-12-28T00:00:00Z",
  "granularity": "day"
}

GET /analytics/usage

Get usage metrics for billing.

Response:

{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "period_start": "2025-12-01T00:00:00Z",
  "period_end": "2025-12-28T23:59:59Z",
  "documents_uploaded": 125,
  "documents_processed": 120,
  "searches_performed": 4520,
  "api_requests": 28500,
  "storage_bytes": 52428800,
  "embedding_tokens": 458000,
  "embedding_cost_usd": 9.16
}

Tenants

POST /tenants

Create a new tenant (self-service signup).

Request:

{
  "name": "Acme Corporation",
  "owner_email": "admin@acme.com",
  "owner_name": "John Smith",
  "slug": "acme-corp",
  "subscription_tier": "pro",
  "trial_days": 14
}

GET /tenants/me

Get current tenant details.

PATCH /tenants/me

Update tenant settings.

GET /tenants/me/usage

Get current billing period usage.

GET /tenants/me/users

List all users in tenant.

POST /tenants/me/users

Add user to tenant.

Request:

{
  "email": "developer@acme.com",
  "name": "Jane Developer",
  "role": "editor"
}

GET /tenants/me/api-keys

List API keys.

POST /tenants/me/api-keys

Create new API key.

Request:

{
  "name": "Production API Key",
  "scopes": ["read", "search", "write"],
  "expires_in_days": 365
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Key",
  "key_prefix": "dms_prod_sk",
  "scopes": ["read", "search", "write"],
  "expires_at": "2026-12-28T00:00:00Z",
  "created_at": "2025-12-28T12:00:00Z",
  "key": "dms_prod_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Note: The full key is only returned once at creation time.

Webhooks

Configure webhooks to receive real-time notifications.

Events

Event	Description
`document.created`	New document uploaded
`document.processed`	Document processing complete
`document.failed`	Document processing failed
`document.deleted`	Document deleted
`search.performed`	Search executed
`tenant.quota.warning`	Approaching quota limit (80%)
`tenant.quota.exceeded`	Quota limit exceeded

Payload Format

{
  "id": "evt_xxxxxxxxxxxxxxxx",
  "type": "document.processed",
  "created": "2025-12-28T12:00:00Z",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Security Guide",
      "status": "completed",
      "chunk_count": 24
    }
  }
}

Verification

Verify webhook signatures using the X-Webhook-Signature header:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

SDKs

Official SDKs are available for:

Python: pip install coditect-dms
TypeScript/JavaScript: npm install @coditect/dms-client
Go: go get github.com/coditect-ai/dms-go

See SDK Documentation for usage examples.

OpenAPI Specification

Download the complete OpenAPI specification:

OpenAPI YAML
Swagger UI (Development only)
ReDoc (Development only)

Support

Documentation: https://docs.coditect.ai
Email: support@az1.ai
Status: https://status.coditect.ai
GitHub Issues: https://github.com/coditect-ai/coditect-rollout-master/issues

Overview​

Authentication​

JWT Token Authentication​

API Key Authentication​

Rate Limiting​

Error Handling​

Common Error Codes​

Endpoints​

Health Checks​

GET /health​

GET /health/ready​

GET /health/live​

Search​

POST /search​

POST /search/graphrag​

GET /search/suggest​

Documents​

GET /documents​

POST /documents​

POST /documents/upload​

GET /documents/{doc_id}​

PUT /documents/{doc_id}​

DELETE /documents/{doc_id}​

GET /documents/{doc_id}/chunks​

POST /documents/{doc_id}/reprocess​

Analytics​

GET /analytics/dashboard​

POST /analytics/metrics​

GET /analytics/usage​

Tenants​

POST /tenants​

GET /tenants/me​

PATCH /tenants/me​

GET /tenants/me/usage​

GET /tenants/me/users​

POST /tenants/me/users​

GET /tenants/me/api-keys​

POST /tenants/me/api-keys​

Webhooks​

Events​

Payload Format​

Verification​

SDKs​

OpenAPI Specification​

Support​

Overview

Authentication

JWT Token Authentication

API Key Authentication

Rate Limiting

Error Handling

Common Error Codes

Endpoints

Health Checks

GET /health

GET /health/ready

GET /health/live

Search

POST /search

POST /search/graphrag

GET /search/suggest

Documents

GET /documents

POST /documents

POST /documents/upload

GET /documents/{doc_id}

PUT /documents/{doc_id}

DELETE /documents/{doc_id}

GET /documents/{doc_id}/chunks

POST /documents/{doc_id}/reprocess

Analytics

GET /analytics/dashboard

POST /analytics/metrics

GET /analytics/usage

Tenants

POST /tenants

GET /tenants/me

PATCH /tenants/me

GET /tenants/me/usage

GET /tenants/me/users

POST /tenants/me/users

GET /tenants/me/api-keys

POST /tenants/me/api-keys

Webhooks

Events

Payload Format

Verification

SDKs

OpenAPI Specification

Support