Inherent
Get started

API Documentation

Complete developer guide for integrating with Inherent's API. Upload documents, search content, and build AI applications.

Table of Contents

Overview

Base URL
http://localhost:4000

All API endpoints are prefixed with /api/v1

Content Types
  • application/json - For most requests
  • multipart/form-data - For file uploads
Response Format

All responses are JSON objects. Successful responses include the requested data:

{
  "data": { ... },
  "message": "Success"
}

Error responses follow a consistent format (see Error Handling section).

Authentication

Header-Based Authentication
Inherent uses email-based authentication via HTTP headers

All authenticated requests require the X-User-Email header containing the user's email address. The system will resolve the email to a user ID internally.

Required Header

X-User-Email: user@example.com

Example Request

curl -X GET "http://localhost:4000/api/v1/workspaces" \
  -H "X-User-Email: user@example.com"

User Registration

Users must be registered before making API calls. Register through the web interface or contact support.

Error Responses

401 Unauthorized

Missing or invalid authentication header

{
  "error": "User email is required. Please provide X-User-Email header.",
  "requestId": "req_123456"
}

404 Not Found

User not found for the provided email

{
  "error": "User not found for the provided email",
  "requestId": "req_123456"
}

Quick Start

Complete Example: Upload and Retrieve Document

Step 1: Create a Workspace

Request

curl -X POST "http://localhost:4000/api/v1/workspaces" \
  -H "X-User-Email: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workspace",
    "description": "My first workspace"
  }'

Response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "My Workspace",
  "description": "My first workspace",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Step 2: Upload a Document

Request

curl -X POST "http://localhost:4000/api/v1/workspaces/{workspaceId}/documents" \
  -H "X-User-Email: user@example.com" \
  -F "file=@document.pdf" \
  -F "metadata={\"category\": \"research\"}" \
  -F "tags=research,important"

Response

{
  "_id": "507f1f77bcf86cd799439012",
  "workspace_id": "507f1f77bcf86cd799439011",
  "user_id": "507f1f77bcf86cd799439010",
  "filename": "document.pdf",
  "original_filename": "document.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245760,
  "status": "uploaded",
  "created_at": "2024-01-15T10:35:00Z"
}

Step 3: Check Document Status

Request

curl -X GET "http://localhost:4000/api/v1/documents/{documentId}" \
  -H "X-User-Email: user@example.com"

Response

{
  "_id": "507f1f77bcf86cd799439012",
  "status": "ready",
  "filename": "document.pdf",
  "size_bytes": 245760,
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:36:00Z"
}

Document Upload

POST/api/v1/workspaces/:workspaceId/documents
Upload a document to a workspace. Documents are processed asynchronously after upload.

Path Parameters

  • workspaceId - The workspace ID (required)

Form Data

  • file - The file to upload (required, max 50MB)
  • metadata - JSON string of additional metadata (optional)
  • tags - Comma-separated list of tags (optional)

Request

curl -X POST "http://localhost:4000/api/v1/workspaces/{workspaceId}/documents" \
  -H "X-User-Email: user@example.com" \
  -F "file=@document.pdf" \
  -F "metadata={\"category\": \"research\", \"author\": \"John Doe\"}" \
  -F "tags=research,important"

Response

{
  "_id": "507f1f77bcf86cd799439012",
  "workspace_id": "507f1f77bcf86cd799439011",
  "user_id": "507f1f77bcf86cd799439010",
  "filename": "document_abc123.pdf",
  "original_filename": "document.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245760,
  "storage_backend": "gcs",
  "storage_path": "workspaces/507f1f77bcf86cd799439011/documents/document_abc123.pdf",
  "status": "uploaded",
  "metadata": {
    "category": "research",
    "author": "John Doe"
  },
  "tags": ["research", "important"],
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Document Processing

After upload, documents are processed asynchronously. The status will change from uploaded → processing → ready. Use the GET endpoint to check status.

Document Management

GET/api/v1/workspaces/:workspaceId/documents
List all documents in a workspace with optional filtering and pagination

Query Parameters

  • user_id - Filter by user ID (optional)
  • status - Filter by status: pending, uploaded, processing, ready, failed (optional)
  • limit - Maximum results (default: 50, max: 200)
  • offset - Pagination offset (default: 0)

Request

curl -X GET "http://localhost:4000/api/v1/workspaces/{workspaceId}/documents?status=ready&limit=10" \
  -H "X-User-Email: user@example.com"

Response

{
  "documents": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "filename": "document.pdf",
      "status": "ready",
      "size_bytes": 245760,
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
GET/api/v1/documents/:id
Get detailed information about a specific document

Request

curl -X GET "http://localhost:4000/api/v1/documents/{documentId}" \
  -H "X-User-Email: user@example.com"

Response

{
  "_id": "507f1f77bcf86cd799439012",
  "workspace_id": "507f1f77bcf86cd799439011",
  "user_id": "507f1f77bcf86cd799439010",
  "filename": "document_abc123.pdf",
  "original_filename": "document.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245760,
  "storage_backend": "gcs",
  "storage_path": "workspaces/507f1f77bcf86cd799439011/documents/document_abc123.pdf",
  "status": "ready",
  "metadata": {
    "category": "research"
  },
  "tags": ["research", "important"],
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:36:00Z"
}
GET/api/v1/documents/:id/download
Get a signed download URL for a document

Request

curl -X GET "http://localhost:4000/api/v1/documents/{documentId}/download" \
  -H "X-User-Email: user@example.com"

Response

{
  "download_url": "https://storage.googleapis.com/bucket/path/to/file?signature=...",
  "expires_at": "2024-01-15T11:35:00Z"
}
PATCH/api/v1/documents/:id/status
Update the status of a document (admin only)

Request Body

{
  "status": "ready"
}

Request

curl -X PATCH "http://localhost:4000/api/v1/documents/{documentId}/status" \
  -H "X-User-Email: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{"status": "ready"}'
DELETE/api/v1/documents/:id
Delete a document and all associated chunks

Request

curl -X DELETE "http://localhost:4000/api/v1/documents/{documentId}" \
  -H "X-User-Email: user@example.com"

Response

{
  "message": "Document deleted successfully"
}

Search & Retrieval

Model Context Protocol (MCP)
Document search and retrieval is available through the MCP server

Inherent provides semantic search capabilities through the Model Context Protocol (MCP) server. This allows AI applications to search and retrieve relevant document chunks based on queries.

MCP Server Connection

Connect to the MCP server using the ingestion service endpoint:

# MCP server runs on the ingestion service
# Default: http://localhost:8000 (or your deployment URL)

Search Tool

Use the search_documents tool to search for content:

{
  "tool": "search_documents",
  "arguments": {
    "workspace_id": "507f1f77bcf86cd799439011",
    "query": "machine learning algorithms",
    "limit": 10
  }
}

Search Capabilities

  • Semantic Search: Uses Weaviate for vector-based semantic search
  • BM25 Search: Keyword-based search using BM25 algorithm
  • Full-Text Search: PostgreSQL fallback for text matching
  • Multi-Tenant: Results are scoped to user and workspace

MCP Integration

For detailed MCP integration instructions, see the ingestion service documentation. The MCP server provides tools for searching, retrieving chunks, and accessing workspace statistics.

Workspace Management

GET/api/v1/workspaces
List all workspaces for the authenticated user

Request

curl -X GET "http://localhost:4000/api/v1/workspaces" \
  -H "X-User-Email: user@example.com"

Response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "My Workspace",
    "description": "My first workspace",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
POST/api/v1/workspaces
Create a new workspace

Request Body

{
  "name": "My Workspace",
  "description": "Workspace description (optional)"
}

Request

curl -X POST "http://localhost:4000/api/v1/workspaces" \
  -H "X-User-Email: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workspace",
    "description": "My first workspace"
  }'
GET/api/v1/workspaces/:id
Get detailed information about a specific workspace

Request

curl -X GET "http://localhost:4000/api/v1/workspaces/{workspaceId}" \
  -H "X-User-Email: user@example.com"
PUT/api/v1/workspaces/:id
Update a workspace

Request Body

{
  "name": "Updated Workspace Name",
  "description": "Updated description"
}

Request

curl -X PUT "http://localhost:4000/api/v1/workspaces/{workspaceId}" \
  -H "X-User-Email: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workspace Name",
    "description": "Updated description"
  }'
DELETE/api/v1/workspaces/:id
Delete a workspace and all associated documents

Request

curl -X DELETE "http://localhost:4000/api/v1/workspaces/{workspaceId}" \
  -H "X-User-Email: user@example.com"

Response

{
  "message": "Workspace deleted successfully"
}

Error Handling

HTTP Status Codes
200

OK

Request successful

201

Created

Resource created successfully

400

Bad Request

Invalid request parameters or body

401

Unauthorized

Missing or invalid authentication

402

Payment Required

Usage limit exceeded (see Rate Limits)

403

Forbidden

Read-only access or insufficient permissions

404

Not Found

Resource not found

500

Internal Server Error

Server error occurred

Error Response Format

All error responses follow a consistent format:

{
  "error": "Error message describing what went wrong",
  "requestId": "req_1234567890",
  "details": {
    // Additional error context (optional)
  }
}

Example Error Responses

Validation Error (400)

{
  "error": "File is required. Use multipart/form-data with 'file' field",
  "requestId": "req_1234567890"
}

Rate Limit Exceeded (402)

{
  "error": "API call limit exceeded",
  "message": "Your Pro plan allows unlimited calls/month. Current usage: 10000. Upgrade for unlimited API calls.",
  "usage": {
    "current": 10000,
    "limit": -1
  },
  "upgrade_url": "/dashboard/billing"
}

Rate Limits & Usage

Plan-Based Limits
PlanStorageAPI Calls/Month
StandardRead-onlyRead-only
Pro10 GBUnlimited
Pro Max50 GBUnlimited
EnterpriseUnlimitedUnlimited
Usage Tracking

API calls are automatically tracked and counted. When limits are approached or exceeded, you'll receive appropriate error responses (402 Payment Required).

Rate Limit Headers

Response headers include usage information:

X-RateLimit-Limit: -1
X-RateLimit-Remaining: -1
X-RateLimit-Reset: 1705320000
Subscription Status

Your subscription status affects API access:

  • Active/Trialing: Full access to all features
  • Past Due: Read-only access until payment is updated
  • Paused: Read-only access
  • Cancelled: Read-only access

Ready to Get Started?

Start building with Inherent's API today.

Get StartedContact Support