Meridian AI - Context Infrastructure for AI Agents

Authentication

All API v1 endpoints require API key authentication using a Bearer token. API keys are generated through the web dashboard and follow the format: kt_xxxxxxxxxxxxx

Headers

Authorization: Bearer <api_key>
Content-Type: application/json

Example

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/smart" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Nike say about our API?",
    "limit": 10
  }'

Smart Search

Intelligent search with automatic entity extraction and knowledge graph filtering.

Endpoint

POST /api/v1/search/smart

Request Parameters

querystring (required)

Natural language search query

limitinteger (optional)

Number of results to return (default: 10, max: 100)

offsetinteger (optional)

Pagination offset (default: 0)

deterministicboolean (optional)

Return all matching chunks vs top results (default: false)

afterstring (optional)

ISO 8601 timestamp - filter results after this date

beforestring (optional)

ISO 8601 timestamp - filter results before this date

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/smart" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Nike say about our API?",
    "limit": 10
  }'

Example Response

{
  "results": [
    {
      "content": "Nike requested API improvements during the Q4 planning call...",
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "chunk_index": 5,
      "score": 0.95,
      "metadata": {
        "file_name": "Q4 Planning Meeting Transcript",
        "source_type": "microsoft-teams",
        "created_at": "2024-01-10T14:30:00Z",
        "entities": [
          {
            "id": "ACCOUNT::nike-uuid",
            "name": "Nike",
            "type": "ACCOUNT"
          }
        ]
      }
    }
  ],
  "total": 15,
  "query_analysis": {
    "original_query": "What did Nike say about our API in recent calls?",
    "extracted_entities": ["Nike", "API"],
    "matched_entities": [
      {
        "id": "ACCOUNT::nike-uuid",
        "name": "Nike",
        "type": "ACCOUNT",
        "confidence": 0.98
      }
    ],
    "execution_time_ms": 245
  }
}

RAG Search

Pure semantic search without knowledge graph extraction. Faster and suitable for broad technical searches.

Endpoint

POST /api/v1/search/rag

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/rag" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "JWT authentication implementation",
    "sources": ["github"],
    "limit": 15
  }'

Filtered Smart Search

Manual filters combined with automatic KG extraction. Ideal for progressive refinement workflows.

Endpoint

POST /api/v1/search/smart/filtered

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/smart/filtered" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what features were discussed?",
    "filters": {
      "entity_ids": ["ACCOUNT::nike-uuid"],
      "sources": ["microsoft-teams"]
    },
    "limit": 10
  }'

Filtered RAG Search

Pure RAG search with manually specified filters. Maximum control and fastest performance.

Endpoint

POST /api/v1/search/rag/filtered

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/rag/filtered" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "api implementation",
    "filters": {
      "entity_ids": ["EMPLOYEE::john-uuid"],
      "sources": ["github"]
    },
    "limit": 20
  }'

Entity Lookup

Deterministic retrieval by entity criteria without semantic search. Returns ALL documents matching criteria.

Endpoint

POST /api/v1/search/by-entities

Request Parameters

entity_typestring (required)

Entity type (e.g., "GITHUB_PR", "MEETING", "ACCOUNT")

entity_idsarray (optional)

Specific entity IDs to filter by

attributesobject (optional)

Filter by entity attributes (e.g., {"state": "merged"})

group_bystring (optional)

Grouping mode - "entity", "document", or "none" (default: "entity")

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/by-entities" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "GITHUB_PR",
    "attributes": {"state": "merged"},
    "after": "2024-11-07T00:00:00Z",
    "limit": 50,
    "group_by": "entity"
  }'

Agent Query

Conversational query endpoint that uses an agent to intelligently search and synthesize information across your knowledge base.

Endpoint

POST /v1/agent/query

Request Parameters

questionstring (required)

The question or query to ask

max_iterationsinteger (optional)

Maximum number of iterations for the agent to perform (default: 5)

Example Request

curl -X POST https://webhooks.trymeridian.dev/v1/agent/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: kt_your_api_key_here" \
  -d '{
    "question": "What did we discuss about the API migration last week?",
    "max_iterations": 5
  }'

Note: This endpoint uses an intelligent agent that can perform multiple search iterations and synthesize information from multiple sources to provide comprehensive answers to complex questions.

Query Knowledge Graph

Discover entities, relationships, and semantic connections.

Endpoint

POST /api/v1/kg/query

Request Parameters

querystring (required)

Natural language query about relationships

depthinteger (optional)

Relationship traversal depth (default: 1, max: 3)

relationship_typesarray (optional)

Filter by relationship types (e.g., ["PARTICIPATES_IN", "WORKS_WITH"])

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/kg/query" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who participates in meetings with Nike?",
    "depth": 1,
    "limit": 50
  }'

Get Document

Retrieve complete parsed document content by document ID.

Endpoint

GET /api/v1/documents/{document_id}

Query Parameters

formatstring (optional)

Document format - "parsed" (default), "native", "pdf", or "metadata"

Example Request

curl -X GET "https://webhooks.trymeridian.dev/api/v1/documents/550e8400-e29b-41d4-a716-446655440000?format=parsed" \
  -H "Authorization: Bearer kt_abc123def456ghi789"

Usage Statistics

Get API usage statistics showing basic vs agent search call counts.

Endpoint

GET /api/v1/usage

Query Parameters

start_datestring (optional)

Start date in ISO format (default: 30 days ago)

end_datestring (optional)

End date in ISO format (default: now)

Example Request

curl -X GET "https://webhooks.trymeridian.dev/api/v1/usage?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer kt_abc123def456ghi789"

Example Response

{
  "basic_search_count": 125,
  "agent_search_count": 85,
  "total_count": 210,
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z"
}

Endpoint Categories:

Basic Search: /api/v1/search/rag, /api/v1/search/rag/filtered, /api/v1/documents/{ id}
Agent Search: /api/v1/search/smart, /api/v1/search/smart/filtered, /api/v1/search/by-entities, /api/v1/kg/query

Unified Context Search (MCP)

Smart search with automatic KG extraction in MCP (Model Context Protocol) format for AI agent integration.

Endpoint

POST /api/v1/mcp/search-unified-context

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/mcp/search-unified-context" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Nike say about our API?",
    "limit": 10
  }'

RAG Search (MCP)

Pure semantic search without KG filtering in MCP format.

Endpoint

POST /api/v1/mcp/search-rag

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/mcp/search-rag" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "JWT authentication",
    "sources": ["github"],
    "limit": 15
  }'

Query Knowledge Graph (MCP)

Discover entities and relationships in MCP format.

Endpoint

POST /api/v1/mcp/query-kg

Example Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/mcp/query-kg" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who participates in meetings with Nike?",
    "depth": 1,
    "limit": 50
  }'

Health Check

Check API health and version.

Endpoint

GET /api/v1/health

Example Request

curl -X GET "https://webhooks.trymeridian.dev/api/v1/health" \
  -H "Authorization: Bearer kt_abc123def456ghi789"

Example Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Responses

All endpoints may return the following error responses.

400 Bad Request

{
  "detail": "Invalid request parameters"
}

401 Unauthorized

{
  "detail": "Invalid API key"
}

404 Not Found

{
  "detail": "Resource not found"
}

500 Internal Server Error

{
  "detail": "An internal server error occurred"
}

Rate Limiting

Rate limits are applied per API key based on your tier.

Rate Limits

Free Tier100 requests/hour

Pro Tier1,000 requests/hour

EnterpriseUnlimited

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000

Rate Limit Exceeded Response

{
  "detail": "Rate limit exceeded. Please try again later.",
  "retry_after": 3600
}

API Reference

Authentication

Headers

Example

Smart Search

Endpoint

Request Parameters

Example Request

Example Response

RAG Search

Endpoint

Example Request

Filtered Smart Search

Endpoint

Example Request

Filtered RAG Search

Endpoint

Example Request

Entity Lookup

Endpoint

Request Parameters

Example Request

Agent Query

Endpoint

Request Parameters

Example Request

Query Knowledge Graph

Endpoint

Request Parameters

Example Request

Get Document

Endpoint

Query Parameters

Example Request

Usage Statistics

Endpoint

Query Parameters

Example Request

Example Response

Unified Context Search (MCP)

Endpoint

Example Request

RAG Search (MCP)

Endpoint

Example Request

Query Knowledge Graph (MCP)

Endpoint

Example Request

Health Check

Endpoint

Example Request

Example Response

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Rate Limiting

Rate Limits

Rate Limit Headers

Rate Limit Exceeded Response