1025 lines
28 KiB
YAML
1025 lines
28 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: HCFS API
|
|
description: |
|
|
Context-Aware Hierarchical Context File System API
|
|
|
|
A production-grade API for managing, searching, and analyzing hierarchical context data with advanced AI capabilities.
|
|
|
|
## Features
|
|
|
|
- **Context Management**: Full CRUD operations for hierarchical contexts
|
|
- **Intelligent Search**: Semantic, keyword, and hybrid search capabilities
|
|
- **Batch Operations**: High-throughput batch processing
|
|
- **Real-time Updates**: WebSocket streaming for live updates
|
|
- **Enterprise Security**: JWT and API key authentication
|
|
- **Performance Monitoring**: Built-in metrics and health checks
|
|
|
|
## Authentication
|
|
|
|
This API supports two authentication methods:
|
|
|
|
1. **API Key**: Include `X-API-Key` header with your API key
|
|
2. **JWT Token**: Include `Authorization: Bearer <token>` header
|
|
|
|
Contact support@hcfs.dev for API access.
|
|
|
|
version: 2.0.0
|
|
contact:
|
|
name: HCFS Support
|
|
email: support@hcfs.dev
|
|
url: https://hcfs.dev/support
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
termsOfService: https://hcfs.dev/terms
|
|
|
|
servers:
|
|
- url: https://api.hcfs.dev/v1
|
|
description: Production server
|
|
- url: https://staging-api.hcfs.dev/v1
|
|
description: Staging server
|
|
- url: http://localhost:8000
|
|
description: Local development server
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
summary: Health Check
|
|
description: Check the health status of the API and its components
|
|
operationId: getHealth
|
|
tags:
|
|
- System
|
|
responses:
|
|
'200':
|
|
description: System is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HealthResponse'
|
|
example:
|
|
status: "healthy"
|
|
version: "2.0.0"
|
|
uptime_seconds: 86400
|
|
components:
|
|
- name: "database"
|
|
status: "healthy"
|
|
response_time_ms: 2.5
|
|
- name: "embeddings"
|
|
status: "healthy"
|
|
response_time_ms: 15.2
|
|
|
|
/api/v1/contexts:
|
|
get:
|
|
summary: List Contexts
|
|
description: Retrieve a paginated list of contexts with optional filtering
|
|
operationId: listContexts
|
|
tags:
|
|
- Contexts
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: Page number (starts from 1)
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
- name: page_size
|
|
in: query
|
|
description: Number of items per page
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 20
|
|
- name: path_prefix
|
|
in: query
|
|
description: Filter by path prefix
|
|
schema:
|
|
type: string
|
|
example: "/docs"
|
|
- name: author
|
|
in: query
|
|
description: Filter by author
|
|
schema:
|
|
type: string
|
|
- name: status
|
|
in: query
|
|
description: Filter by status
|
|
schema:
|
|
$ref: '#/components/schemas/ContextStatus'
|
|
- name: sort_by
|
|
in: query
|
|
description: Sort field
|
|
schema:
|
|
type: string
|
|
enum: [created_at, updated_at, path, author]
|
|
default: created_at
|
|
- name: sort_order
|
|
in: query
|
|
description: Sort order
|
|
schema:
|
|
type: string
|
|
enum: [asc, desc]
|
|
default: desc
|
|
responses:
|
|
'200':
|
|
description: List of contexts
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextListResponse'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'429':
|
|
$ref: '#/components/responses/RateLimited'
|
|
|
|
post:
|
|
summary: Create Context
|
|
description: Create a new context with automatic embedding generation
|
|
operationId: createContext
|
|
tags:
|
|
- Contexts
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextCreate'
|
|
example:
|
|
path: "/docs/api-guide"
|
|
content: "This is a comprehensive guide to using the HCFS API..."
|
|
summary: "API usage guide"
|
|
author: "docs-team"
|
|
tags: ["documentation", "api", "guide"]
|
|
metadata:
|
|
category: "documentation"
|
|
difficulty: "beginner"
|
|
responses:
|
|
'200':
|
|
description: Context created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextDetailResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ValidationError'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'429':
|
|
$ref: '#/components/responses/RateLimited'
|
|
|
|
/api/v1/contexts/{context_id}:
|
|
get:
|
|
summary: Get Context
|
|
description: Retrieve a specific context by ID
|
|
operationId: getContext
|
|
tags:
|
|
- Contexts
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: context_id
|
|
in: path
|
|
required: true
|
|
description: Context identifier
|
|
schema:
|
|
type: integer
|
|
example: 123
|
|
responses:
|
|
'200':
|
|
description: Context details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextDetailResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
put:
|
|
summary: Update Context
|
|
description: Update an existing context
|
|
operationId: updateContext
|
|
tags:
|
|
- Contexts
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: context_id
|
|
in: path
|
|
required: true
|
|
description: Context identifier
|
|
schema:
|
|
type: integer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextUpdate'
|
|
responses:
|
|
'200':
|
|
description: Context updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ContextDetailResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ValidationError'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
delete:
|
|
summary: Delete Context
|
|
description: Delete a context permanently
|
|
operationId: deleteContext
|
|
tags:
|
|
- Contexts
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: context_id
|
|
in: path
|
|
required: true
|
|
description: Context identifier
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Context deleted successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
/api/v1/search:
|
|
post:
|
|
summary: Search Contexts
|
|
description: |
|
|
Search contexts using various search methods:
|
|
|
|
- **Semantic Search**: Uses AI embeddings for meaning-based search
|
|
- **Keyword Search**: Traditional text-based search
|
|
- **Hybrid Search**: Combines semantic and keyword search
|
|
- **Fuzzy Search**: Tolerates typos and variations
|
|
operationId: searchContexts
|
|
tags:
|
|
- Search
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchRequest'
|
|
examples:
|
|
semantic_search:
|
|
summary: Semantic Search
|
|
value:
|
|
query: "machine learning algorithms"
|
|
search_type: "semantic"
|
|
top_k: 10
|
|
similarity_threshold: 0.7
|
|
hybrid_search:
|
|
summary: Hybrid Search
|
|
value:
|
|
query: "neural networks deep learning"
|
|
search_type: "hybrid"
|
|
semantic_weight: 0.7
|
|
top_k: 20
|
|
path_prefix: "/ml"
|
|
responses:
|
|
'200':
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ValidationError'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
/api/v1/contexts/batch:
|
|
post:
|
|
summary: Batch Create Contexts
|
|
description: Create multiple contexts in a single operation
|
|
operationId: batchCreateContexts
|
|
tags:
|
|
- Batch Operations
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BatchContextCreate'
|
|
responses:
|
|
'200':
|
|
description: Batch operation results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BatchResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ValidationError'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
/api/v1/stats:
|
|
get:
|
|
summary: Get Statistics
|
|
description: Retrieve comprehensive system statistics and metrics
|
|
operationId: getStatistics
|
|
tags:
|
|
- Analytics
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: System statistics
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StatsResponse'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
/metrics:
|
|
get:
|
|
summary: Prometheus Metrics
|
|
description: Get Prometheus-compatible metrics for monitoring
|
|
operationId: getMetrics
|
|
tags:
|
|
- System
|
|
responses:
|
|
'200':
|
|
description: Prometheus metrics
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: |
|
|
# HELP hcfs_requests_total Total HTTP requests
|
|
# TYPE hcfs_requests_total counter
|
|
hcfs_requests_total{method="GET",endpoint="/api/v1/contexts",status="200"} 1250
|
|
|
|
# HELP hcfs_request_duration_seconds HTTP request duration
|
|
# TYPE hcfs_request_duration_seconds histogram
|
|
hcfs_request_duration_seconds_bucket{le="0.1"} 800
|
|
hcfs_request_duration_seconds_bucket{le="0.5"} 1200
|
|
hcfs_request_duration_seconds_bucket{le="1.0"} 1245
|
|
hcfs_request_duration_seconds_bucket{le="+Inf"} 1250
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-Key
|
|
description: API key for authentication
|
|
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT token for authentication
|
|
|
|
schemas:
|
|
ContextStatus:
|
|
type: string
|
|
enum: [active, archived, deleted, draft]
|
|
description: Status of the context
|
|
example: active
|
|
|
|
SearchType:
|
|
type: string
|
|
enum: [semantic, keyword, hybrid, fuzzy]
|
|
description: Type of search to perform
|
|
example: semantic
|
|
|
|
HealthStatus:
|
|
type: string
|
|
enum: [healthy, degraded, unhealthy]
|
|
description: Health status indicator
|
|
|
|
ComponentHealth:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Component name
|
|
status:
|
|
$ref: '#/components/schemas/HealthStatus'
|
|
response_time_ms:
|
|
type: number
|
|
format: float
|
|
description: Response time in milliseconds
|
|
error_message:
|
|
type: string
|
|
description: Error message if unhealthy
|
|
required: [name, status]
|
|
|
|
HealthResponse:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/HealthStatus'
|
|
version:
|
|
type: string
|
|
description: API version
|
|
uptime_seconds:
|
|
type: number
|
|
description: System uptime in seconds
|
|
components:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ComponentHealth'
|
|
required: [status, version, uptime_seconds, components]
|
|
|
|
Context:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: Unique context identifier
|
|
example: 123
|
|
path:
|
|
type: string
|
|
description: Hierarchical path of the context
|
|
example: "/docs/api/authentication"
|
|
content:
|
|
type: string
|
|
description: Content of the context
|
|
summary:
|
|
type: string
|
|
description: Brief summary of the context
|
|
author:
|
|
type: string
|
|
description: Author of the context
|
|
example: "john.doe"
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags associated with the context
|
|
example: ["api", "authentication", "security"]
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Additional metadata
|
|
status:
|
|
$ref: '#/components/schemas/ContextStatus'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Last update timestamp
|
|
version:
|
|
type: integer
|
|
description: Context version number
|
|
example: 1
|
|
similarity_score:
|
|
type: number
|
|
format: float
|
|
description: Similarity score (for search results)
|
|
minimum: 0.0
|
|
maximum: 1.0
|
|
required: [id, path, content, status, created_at, updated_at, version]
|
|
|
|
ContextCreate:
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: Hierarchical path of the context
|
|
example: "/docs/quickstart"
|
|
pattern: "^/.*"
|
|
content:
|
|
type: string
|
|
description: Content of the context
|
|
minLength: 1
|
|
maxLength: 1000000
|
|
summary:
|
|
type: string
|
|
description: Brief summary of the context
|
|
maxLength: 1000
|
|
author:
|
|
type: string
|
|
description: Author of the context
|
|
maxLength: 100
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 50
|
|
description: Tags associated with the context
|
|
maxItems: 20
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Additional metadata
|
|
required: [path, content]
|
|
|
|
ContextUpdate:
|
|
type: object
|
|
properties:
|
|
content:
|
|
type: string
|
|
description: Updated content
|
|
minLength: 1
|
|
maxLength: 1000000
|
|
summary:
|
|
type: string
|
|
description: Updated summary
|
|
maxLength: 1000
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 50
|
|
maxItems: 20
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
status:
|
|
$ref: '#/components/schemas/ContextStatus'
|
|
|
|
SearchRequest:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
description: Search query
|
|
minLength: 1
|
|
maxLength: 1000
|
|
example: "machine learning algorithms"
|
|
search_type:
|
|
$ref: '#/components/schemas/SearchType'
|
|
top_k:
|
|
type: integer
|
|
description: Maximum number of results
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 10
|
|
similarity_threshold:
|
|
type: number
|
|
format: float
|
|
description: Minimum similarity score
|
|
minimum: 0.0
|
|
maximum: 1.0
|
|
default: 0.0
|
|
path_prefix:
|
|
type: string
|
|
description: Search within path prefix
|
|
example: "/docs"
|
|
semantic_weight:
|
|
type: number
|
|
format: float
|
|
description: Weight for semantic search in hybrid mode
|
|
minimum: 0.0
|
|
maximum: 1.0
|
|
default: 0.7
|
|
filters:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Additional search filters
|
|
required: [query]
|
|
|
|
SearchResult:
|
|
type: object
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
score:
|
|
type: number
|
|
format: float
|
|
description: Relevance score
|
|
minimum: 0.0
|
|
maximum: 1.0
|
|
explanation:
|
|
type: string
|
|
description: Explanation of why this result was returned
|
|
highlights:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Highlighted text snippets
|
|
required: [context, score]
|
|
|
|
SearchResponse:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SearchResult'
|
|
query:
|
|
type: string
|
|
description: Original search query
|
|
search_type:
|
|
$ref: '#/components/schemas/SearchType'
|
|
total_results:
|
|
type: integer
|
|
description: Total number of results found
|
|
search_time_ms:
|
|
type: number
|
|
format: float
|
|
description: Search execution time in milliseconds
|
|
filters_applied:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Filters that were applied
|
|
required: [data, query, search_type, total_results, search_time_ms]
|
|
|
|
BatchContextCreate:
|
|
type: object
|
|
properties:
|
|
contexts:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ContextCreate'
|
|
minItems: 1
|
|
maxItems: 1000
|
|
required: [contexts]
|
|
|
|
BatchOperationResult:
|
|
type: object
|
|
properties:
|
|
success_count:
|
|
type: integer
|
|
description: Number of successful operations
|
|
error_count:
|
|
type: integer
|
|
description: Number of failed operations
|
|
total_items:
|
|
type: integer
|
|
description: Total number of items processed
|
|
created_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: IDs of successfully created contexts
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
index:
|
|
type: integer
|
|
description: Index of the failed item
|
|
path:
|
|
type: string
|
|
description: Path of the failed context
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
required: [success_count, error_count, total_items]
|
|
|
|
PaginationMeta:
|
|
type: object
|
|
properties:
|
|
page:
|
|
type: integer
|
|
description: Current page number
|
|
page_size:
|
|
type: integer
|
|
description: Items per page
|
|
total_items:
|
|
type: integer
|
|
description: Total number of items
|
|
total_pages:
|
|
type: integer
|
|
description: Total number of pages
|
|
has_next:
|
|
type: boolean
|
|
description: Whether there is a next page
|
|
has_previous:
|
|
type: boolean
|
|
description: Whether there is a previous page
|
|
required: [page, page_size, total_items, total_pages, has_next, has_previous]
|
|
|
|
ContextDetailResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
data:
|
|
$ref: '#/components/schemas/Context'
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
api_version:
|
|
type: string
|
|
example: "v1"
|
|
required: [success, data, timestamp, api_version]
|
|
|
|
ContextListResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Context'
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationMeta'
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
api_version:
|
|
type: string
|
|
example: "v1"
|
|
required: [success, data, pagination, timestamp, api_version]
|
|
|
|
BatchResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
data:
|
|
$ref: '#/components/schemas/BatchOperationResult'
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
api_version:
|
|
type: string
|
|
example: "v1"
|
|
required: [success, data, timestamp, api_version]
|
|
|
|
StatsResponse:
|
|
type: object
|
|
properties:
|
|
context_stats:
|
|
type: object
|
|
properties:
|
|
total_contexts:
|
|
type: integer
|
|
contexts_by_status:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
contexts_by_author:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
average_content_length:
|
|
type: number
|
|
format: float
|
|
search_stats:
|
|
type: object
|
|
properties:
|
|
total_searches:
|
|
type: integer
|
|
searches_by_type:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
average_response_time_ms:
|
|
type: number
|
|
format: float
|
|
search_success_rate:
|
|
type: number
|
|
format: float
|
|
system_stats:
|
|
type: object
|
|
properties:
|
|
uptime_seconds:
|
|
type: number
|
|
memory_usage_mb:
|
|
type: number
|
|
format: float
|
|
active_connections:
|
|
type: integer
|
|
cache_hit_rate:
|
|
type: number
|
|
format: float
|
|
database_size_mb:
|
|
type: number
|
|
format: float
|
|
|
|
SuccessResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
message:
|
|
type: string
|
|
example: "Operation completed successfully"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
api_version:
|
|
type: string
|
|
example: "v1"
|
|
required: [success, message, timestamp, api_version]
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: false
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
error_details:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
description: Field that caused the error
|
|
message:
|
|
type: string
|
|
description: Detailed error message
|
|
code:
|
|
type: string
|
|
description: Error code
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
request_id:
|
|
type: string
|
|
description: Unique request identifier
|
|
api_version:
|
|
type: string
|
|
example: "v1"
|
|
required: [success, error, timestamp, api_version]
|
|
|
|
responses:
|
|
Unauthorized:
|
|
description: Authentication required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error: "Authentication required"
|
|
error_details:
|
|
- message: "Valid API key or JWT token required"
|
|
timestamp: "2024-01-15T10:30:00Z"
|
|
api_version: "v1"
|
|
|
|
ValidationError:
|
|
description: Request validation failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error: "Request validation failed"
|
|
error_details:
|
|
- field: "path"
|
|
message: "Path must start with /"
|
|
code: "invalid_format"
|
|
- field: "content"
|
|
message: "Content cannot be empty"
|
|
code: "required"
|
|
timestamp: "2024-01-15T10:30:00Z"
|
|
api_version: "v1"
|
|
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error: "Context not found"
|
|
error_details:
|
|
- message: "Context with ID 123 does not exist"
|
|
timestamp: "2024-01-15T10:30:00Z"
|
|
api_version: "v1"
|
|
|
|
RateLimited:
|
|
description: Rate limit exceeded
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: integer
|
|
description: Seconds to wait before retrying
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: integer
|
|
description: Rate limit ceiling
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: integer
|
|
description: Remaining requests in current window
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: integer
|
|
description: Unix timestamp when rate limit resets
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error: "Rate limit exceeded"
|
|
error_details:
|
|
- message: "Rate limit of 100 requests per minute exceeded"
|
|
timestamp: "2024-01-15T10:30:00Z"
|
|
retry_after: 45
|
|
api_version: "v1"
|
|
|
|
webhooks:
|
|
contextCreated:
|
|
post:
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
event_type:
|
|
type: string
|
|
example: "context_created"
|
|
data:
|
|
$ref: '#/components/schemas/Context'
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
description: Webhook received successfully
|
|
|
|
contextUpdated:
|
|
post:
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
event_type:
|
|
type: string
|
|
example: "context_updated"
|
|
data:
|
|
$ref: '#/components/schemas/Context'
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
description: Webhook received successfully
|
|
|
|
contextDeleted:
|
|
post:
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
event_type:
|
|
type: string
|
|
example: "context_deleted"
|
|
data:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
path:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
description: Webhook received successfully |