Skip to content

API

Jump to bottom
Jihyeok edited this page Aug 21, 2025 · 2 revisions

API Documentation

OpenContext provides two types of APIs: MCP Protocol Tools for AI assistant integration and REST APIs for administrative operations.

MCP Protocol Tools

OpenContext implements the Model Context Protocol to provide AI assistants with secure access to your document knowledge base. The MCP adapter translates MCP tool calls to HTTP requests against the core service.

find_knowledge Tool

Performs exploratory search returning relevant document chunks with metadata.

Purpose: First phase of two-stage retrieval - helps users discover relevant knowledge areas before diving into specific content.

Parameters:

  • query (string, required): Natural language search query
  • topK (integer, optional): Maximum number of results to return (default: 50)

Returns:

{
  "results": [
    {
      "chunkId": "uuid-string",
      "title": "Section title from document",
      "snippet": "First 50 characters of content...",
      "relevanceScore": 0.94
    }
  ]
}

HTTP Mapping: GET /api/v1/search?query={query}&topK={topK}

Example Usage:

{
  "tool_name": "find_knowledge",
  "parameters": {
    "query": "Spring Security JWT configuration",
    "topK": 10
  }
}

get_content Tool

Retrieves full content of a specific document chunk.

Purpose: Second phase of two-stage retrieval - provides complete context for AI assistant to generate accurate responses.

Parameters:

  • chunkId (string, required): UUID of the chunk to retrieve
  • maxTokens (integer, optional): Maximum tokens to return (default: 25000)

Returns:

{
  "content": "Complete chunk content here...",
  "tokenInfo": {
    "tokenizer": "tiktoken-cl100k_base",
    "actualTokens": 1247
  }
}

Token Limiting: If content exceeds maxTokens, text is truncated from the end to preserve important context at the beginning.

HTTP Mapping: POST /api/v1/get-content

Example Usage:

{
  "tool_name": "get_content",
  "parameters": {
    "chunkId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "maxTokens": 8000
  }
}

Administrative REST APIs

All administrative APIs require authentication via X-API-KEY header.

Document Upload

Upload PDF or Markdown files for processing.

Endpoint: POST /api/v1/sources/upload

Headers:

  • Content-Type: multipart/form-data
  • X-API-KEY: your-api-key

Request Body: File uploaded as file parameter in multipart form

Response (202 Accepted):

{
  "success": true,
  "data": {
    "sourceDocumentId": "uuid",
    "originalFilename": "document.pdf",
    "ingestionStatus": "PENDING",
    "message": "File uploaded successfully and is now pending for ingestion."
  },
  "message": "Request processed successfully",
  "errorCode": null,
  "timestamp": "2025-08-21T12:00:00Z"
}

Error Responses:

  • 400 VALIDATION_FAILED: Missing file parameter
  • 403 INSUFFICIENT_PERMISSION: Invalid API key
  • 409 DUPLICATE_FILE_UPLOADED: File already exists (by checksum)
  • 413 PAYLOAD_TOO_LARGE: File exceeds size limit
  • 415 UNSUPPORTED_MEDIA_TYPE: Unsupported file format

Document List

Retrieve paginated list of uploaded documents with current status.

Endpoint: GET /api/v1/sources

Headers:

  • X-API-KEY: your-api-key

Query Parameters:

  • page (integer, optional): Page number starting from 0 (default: 0)
  • size (integer, optional): Items per page (default: 20)
  • sort (string, optional): Sort criteria, e.g., createdAt,desc

Response (200 OK):

{
  "success": true,
  "data": {
    "content": [
      {
        "id": "uuid",
        "originalFilename": "spring-security-reference.pdf",
        "fileType": "PDF",
        "fileSize": 10485760,
        "ingestionStatus": "COMPLETED",
        "errorMessage": null,
        "lastIngestedAt": "2025-08-21T12:00:00Z",
        "createdAt": "2025-08-21T11:50:00Z",
        "updatedAt": "2025-08-21T12:00:00Z"
      }
    ],
    "page": 0,
    "size": 20,
    "totalElements": 48,
    "totalPages": 3,
    "first": true,
    "last": false,
    "hasNext": true,
    "hasPrevious": false
  },
  "message": "Request processed successfully",
  "errorCode": null,
  "timestamp": "2025-08-21T12:05:00Z"
}

Document Reprocessing

Trigger reprocessing of a specific document.

Endpoint: POST /api/v1/sources/{sourceId}/resync

Headers:

  • X-API-KEY: your-api-key

Path Parameters:

  • sourceId (string): UUID of the document to reprocess

Response (202 Accepted):

{
  "success": true,
  "data": {
    "message": "Document reprocessing has been initiated"
  },
  "message": "Request processed successfully",
  "errorCode": null,
  "timestamp": "2025-08-21T12:10:00Z"
}

Error Responses:

  • 404 SOURCE_DOCUMENT_NOT_FOUND: Document does not exist
  • 409 RESOURCE_IS_BEING_PROCESSED: Document is currently being processed

Document Deletion

Delete a document and all associated chunks.

Endpoint: DELETE /api/v1/sources/{sourceId}

Headers:

  • X-API-KEY: your-api-key

Path Parameters:

  • sourceId (string): UUID of the document to delete

Response (202 Accepted):

{
  "success": true,
  "data": {
    "message": "Document deletion has been initiated"
  },
  "message": "Request processed successfully",
  "errorCode": null,
  "timestamp": "2025-08-21T12:15:00Z"
}

Ingestion Status Values

Documents progress through the following status values during processing:

  • PENDING: Uploaded and queued for processing
  • PARSING: Document structure being extracted
  • CHUNKING: Text being divided into searchable chunks
  • EMBEDDING: Generating vector embeddings for semantic search
  • INDEXING: Storing data in Elasticsearch
  • COMPLETED: Successfully processed and searchable
  • ERROR: Processing failed (check errorMessage field)
  • DELETING: Deletion in progress

Error Handling

All API responses follow a standard format. Failed requests return:

{
  "success": false,
  "data": null,
  "message": "Human-readable error description",
  "errorCode": "MACHINE_READABLE_ERROR_CODE",
  "timestamp": "2025-08-21T12:00:00Z"
}

Common Error Codes

Authentication Errors:

  • INSUFFICIENT_PERMISSION: Invalid or missing API key

Validation Errors:

  • VALIDATION_FAILED: Request parameters invalid
  • UNSUPPORTED_MEDIA_TYPE: File format not supported
  • PAYLOAD_TOO_LARGE: File exceeds size limits

Resource Errors:

  • SOURCE_DOCUMENT_NOT_FOUND: Requested document does not exist
  • CHUNK_NOT_FOUND: Requested chunk does not exist
  • CONTENT_NOT_AVAILABLE: Chunk exists but content unavailable

Conflict Errors:

  • DUPLICATE_FILE_UPLOADED: File already exists
  • RESOURCE_IS_BEING_PROCESSED: Operation conflicts with current processing

Infrastructure Errors:

  • EXTERNAL_SERVICE_UNAVAILABLE: Dependency service unavailable
  • DB_CONNECTION_FAILED: Database connectivity issues
  • ELASTICSEARCH_ERROR: Search engine errors

Rate Limiting and Concurrency

Document Processing: Limited to 3 concurrent ingestion operations to prevent system overload.

Search Operations: No explicit rate limiting, but consider implementing client-side throttling for high-volume usage.

File Upload: Single file uploads only, batch upload through multiple API calls.

API Versioning

Current API version is v1. All endpoints are prefixed with /api/v1/.

Future versions will be released as /api/v2/ etc., with backward compatibility maintained for at least one major version.

Testing the API

Using curl

# Upload a document
curl -X POST http://localhost:8080/api/v1/sources/upload \
  -H "X-API-KEY: dev-api-key-123" \
  -F "file=@document.pdf"

# List documents
curl -X GET "http://localhost:8080/api/v1/sources?page=0&size=10" \
  -H "X-API-KEY: dev-api-key-123"

# Search knowledge
curl -X GET "http://localhost:8080/api/v1/search?query=spring security&topK=5"

# Get content
curl -X POST http://localhost:8080/api/v1/get-content \
  -H "Content-Type: application/json" \
  -d '{"chunkId":"your-chunk-id","maxTokens":5000}'

Using the Admin UI

Navigate to http://localhost:3001 for a web interface to:

  • Upload and manage documents
  • Monitor processing status
  • Test search functionality
  • Configure API keys

Testing MCP Integration

# Test MCP adapter directly
echo '{"tool_name": "find_knowledge", "parameters": {"query": "test", "topK": 3}}' | \
  docker compose exec -T open-context-mcp-adapter node /usr/src/app/dist/index.js

Swagger Documentation

Interactive API documentation is available at: http://localhost:8080/swagger-ui/index.html

The Swagger interface provides:

  • Complete API schema
  • Interactive request testing
  • Example requests and responses
  • Model definitions

Project Management

Contributing

Documentation

Clone this wiki locally