API Documentation

API Documentation

Akurion exposes several API surfaces:

Surface	Base path	Best for
Developer REST API	/api/v1/*	Direct integration with project files, search, answer generation, data sources, discovery, and usage.
MCP JSON-RPC API	/mcp-server	MCP-compatible agents and tool callers.
Streaming RAG API	/askme, /mcp, /mcprag	UI-style streaming answer generation.
File access API	/generate-file-url, /file-info/:fileId	Source preview, original file access, and signed URLs.
App control-plane APIs	Authenticated app operation endpoints plus custom HTTP APIs	Akurion web app control-plane behavior.

The primary public developer surface is the REST API under /api/v1/* and the MCP endpoint under /mcp-server.

Authentication

Send the API key in the API-KEY header:

API-KEY: YOUR_API_KEY

Project-scoped keys usually resolve the project automatically. Subscription-scoped keys can access all or selected projects and must provide project context for project-level tools.

Project context can be provided through one of these options:

• X-Project-ID: YOUR_PROJECT_ID
• project_id query parameter
• projectId or project_id JSON body field
• project_id inside MCP params.arguments

Example:

curl -X GET "https://api.structhub.io/api/v1/project/details" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID"

Response Shape

REST developer API responses use:

{
  "status": "success",
  "tool": "answer_query",
  "result": {},
  "meta": {
    "credits_used": 80,
    "execution_time_ms": 1234
  }
}

Errors use:

{
  "status": "error",
  "tool": "answer_query",
  "error": "Project context is required",
  "result": null,
  "meta": {
    "credits_used": 0,
    "execution_time_ms": 10
  }
}

Developer REST API

Base URL:

https://api.structhub.io/api/v1

Account and Tool Discovery

Method	Path	Tool	Project required	Description
GET	/projects	list_accessible_projects	No	List projects available to the API key.
GET	/subscription	get_subscription_details	No	Return subscription/workspace usage summary.
GET	/tools	Tool catalog	No	List all MCP-backed REST tools, schemas, costs, and categories.
GET	/tools/{tool_name}	Tool describe	No	Describe one tool schema and metadata.

Project

Method	Path	Tool	Description
GET	/project/details	get_project_details	Project configuration, credits, optional members, and optional key metadata.
GET	/project/metadata-keys	list_project_metadata_keys	Project metadata keys and definitions.
GET	/project/settings	get_project_settings	Search topK, token limit, metadata prompt, and retrieval configuration.
GET	/project/credit-usage	get_project_credit_usage	Credit usage history, grouped by day/week/month.
GET	/project/file-statistics	get_file_statistics_detailed	File statistics and optional index-level stats.
GET	/project/metadata-coverage	get_metadata_coverage	Metadata coverage across project files.
GET	/project/sync-status	get_sync_status	Data source sync health and timing.
GET	/project/usage-trends	get_project_usage_trends	Credit, file, and search activity trends.

Search and AI

Method	Path	Tool	Description
POST	/search/vector	vector_search	Semantic search over project chunks.
POST	/search/vector/metadata-filter	vector_search_with_metadata_filter	Semantic search with structured metadata filters.
POST	/queries/multi	generate_multi_queries	Expand one query into multiple optimized retrieval queries.
POST	/queries/intelligent-search	intelligent_search	Orchestrated retrieval with intent and metadata handling.
POST	/queries/answer	answer_query	End-to-end answer generation with sources.
POST	/queries/intent	analyze_query_intent	Classify query type and recommend search strategy.
POST	/queries/metadata-extract	extract_metadata_from_query	Extract metadata key/value hints from natural language.

Example answer request:

curl -X POST "https://api.structhub.io/api/v1/queries/answer" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -d '{
    "query": "Compare vendor security requirements across the latest documents",
    "search_mode": "comparative",
    "max_depth": 5,
    "web_search": false
  }'

Example metadata-filtered search:

curl -X POST "https://api.structhub.io/api/v1/search/vector/metadata-filter" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -d '{
    "query": "retention obligations",
    "metadata_filters": {
      "department": { "$eq": "legal" },
      "year": { "$gte": 2025 }
    },
    "top_k": 25
  }'

Supported metadata operators include $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, and $or.

Files

Method	Path	Tool	Description
GET	/project/files/count	get_project_files_count	File totals and optional breakdowns.
GET	/project/files	get_project_files_list	Paginated file list with status/type/source metadata.
GET	/project/files/search	search_files_by_name	SQL-like file name search using % wildcard.
GET	/project/files/status/{status}	get_files_by_status	Files by status such as processing, completed, or failed.
GET	/project/files/type/{file_type}	get_files_by_type	Files by MIME type or extension.
GET	/project/files/date-range	get_files_by_date_range	Files created or updated between two dates.
GET	/project/files/{file_id}	get_file_by_id	File details and optional generated metadata.
POST	/project/files/{file_id}/chunks	get_file_chunks	Chunks from one file with optional ranking query.
GET	/project/files/{file_id}/chunks	get_file_chunks	Query-parameter variant of chunk retrieval.
POST	/project/files/{file_id}/chunks/around-pages	get_chunks_around_page	Chunks around one or more pages.
GET	/project/files/{file_id}/chunks/around-pages	get_chunks_around_page	Query-parameter variant of page context retrieval.
GET	/files/{file_id}/preview	preview_file_content	Initial chunks and optional summary.
POST	/project/files/upload-url	create_file_upload	Create or upsert file record and return signed upload URL.
DELETE	/project/files/{file_id}	delete_file	Delete file and associated vectors.

Example upload URL:

curl -X POST "https://api.structhub.io/api/v1/project/files/upload-url" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -d '{
    "name": "security-policy.pdf",
    "file_type": "application/pdf"
  }'

Data Sources

Method	Path	Tool	Description
GET	/project/data-sources	get_data_sources	List project data sources and status.
POST	/project/data-sources	create_data_source	Create a data source for a source type enabled in your workspace.
PATCH	/project/data-sources/{data_source_id}	update_data_source	Update enabled source settings or source-specific config.
DELETE	/project/data-sources/{data_source_id}	delete_data_source	Delete source and related indexed content.
POST	/project/data-sources/{data_source_id}/resync	resync_data_source	Queue a fresh source sync for enabled source types.

Source connector availability is controlled in the Akurion app. Disabled source types are intentionally not listed in public API docs until they are enabled for customer use.

Chunk Collection

Method	Path	Tool	Description
POST	/chunks/collect/file	collect_chunks_from_file	Ordered chunks for one file.
POST	/chunks/collect/files	collect_chunks_from_multiple_files	Chunks for multiple files.
POST	/files/find/metadata	find_files_by_metadata	Files matching metadata filters.
GET	/files/find/name	find_files_by_name	Files matching wildcard or regex name pattern.
POST	/chunks/collect/metadata-file	collect_chunks_by_metadata_and_file	Chunks from files matching metadata and optional name pattern.
GET	/files/statistics	get_file_statistics	Aggregate collection statistics.
POST	/chunks/collect/page-range	collect_chunks_by_page_range	Chunks from one file page range.
POST	/chunks/collect/batch-page-ranges	batch_collect_by_file_ids_and_pages	Chunks from multiple file/page ranges.

Discovery

Method	Path	Tool	Description
GET	/discovery/metadata-schema	discover_metadata_schema	Infer metadata keys, types, counts, and examples.
GET	/discovery/metadata-values/{metadata_key}	list_metadata_values	Unique values and optional counts for a metadata key.
GET	/discovery/file-structure	explore_file_structure	Corpus structure grouped by type, source pattern, or metadata key.
POST	/discovery/content-topics	discover_content_topics	Discover dominant corpus topics.
GET	/discovery/similar-files/{file_id}	find_similar_files	Files similar by content or metadata.
POST	/discovery/metadata-correlations	analyze_metadata_correlations	Correlations between metadata keys.
POST	/discovery/metadata-combinations	search_metadata_combinations	Complex logical metadata search.

MCP JSON-RPC API

Base URL:

https://api.structhub.io/mcp-server

Alternate JSON-RPC-compatible routes:

• /developer-api
• /api/v1

Initialize:

curl -X POST "https://api.structhub.io/mcp-server" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }'

List tools:

curl -X POST "https://api.structhub.io/mcp-server" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 2
  }'

Call a tool:

curl -X POST "https://api.structhub.io/mcp-server" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "answer_query",
      "arguments": {
        "query": "Summarize this project with citations",
        "search_mode": "focused",
        "max_depth": 5
      }
    },
    "id": 3
  }'

Supported JSON-RPC methods:

Method	Description
initialize	MCP lifecycle handshake.
notifications/initialized	MCP initialization notification.
tools/list or tools.list	List available tools.
tools.describe	Describe one tool.
tools/call or tools.call	Execute one tool.

Standalone MCP Tool Catalog

Low-Level Retrieval Tools

Tool	Credits	Required inputs	Description
vector_search	10	query	Semantic search over the vector store.
vector_search_with_metadata_filter	15	query, metadata_filters	Semantic search constrained by metadata filters.
get_file_chunks	12	file_id	Fetch chunks from a specific file.
get_chunks_around_page	10	file_id, page_numbers	Retrieve chunks around page anchors.
list_project_metadata_keys	5	None	List configured project metadata keys.
get_project_settings	5	None	Return project retrieval settings.

High-Level RAG Tools

Tool	Credits	Required inputs	Description
generate_multi_queries	20	query	Expand one query into multiple search queries.
intelligent_search	40	query	Orchestrated retrieval with metadata handling.
answer_query	80	query	End-to-end answer generation with sources.
analyze_query_intent	15	query	Classify query intent and recommend search strategy.
extract_metadata_from_query	15	query	Suggest applicable metadata filters from a user request.

Collection Tools

Tool	Credits	Required inputs	Description
collect_chunks_from_file	12	file_id	Collect ordered chunks from one file.
collect_chunks_from_multiple_files	20	file_ids	Batch collect chunks from multiple files.
find_files_by_metadata	10	metadata_filters	Find files matching metadata criteria.
find_files_by_name	8	name_pattern	Find files by wildcard or regex-like pattern.
collect_chunks_by_metadata_and_file	18	metadata_filters	Collect chunks by metadata and optional file name pattern.
get_file_statistics	8	None	Aggregate file statistics and breakdowns.
collect_chunks_by_page_range	10	file_id, start_page, end_page	Collect chunks from one page range.
batch_collect_by_file_ids_and_pages	25	file_page_ranges	Batch page-range chunk collection.

Discovery Tools

Tool	Credits	Required inputs	Description
discover_metadata_schema	20	None	Infer metadata schema by sampling indexed documents.
list_metadata_values	8	metadata_key	List values for one metadata key.
explore_file_structure	12	None	Summarize corpus structure.
discover_content_topics	25	None	Discover major topics and representative files.
find_similar_files	15	file_id	Find similar files by content or metadata.
analyze_metadata_correlations	18	metadata_keys	Analyze correlations between metadata keys.
preview_file_content	12	file_id	Preview file chunks and optional summary.
search_metadata_combinations	15	filter_expression	Search with complex metadata logic.

Project Management Tools

Tool	Credits	Required inputs	Description
get_project_files_count	5	None	File counts and breakdowns.
get_project_files_list	8	None	Paginated project file list.
get_project_details	5	None	Project configuration and optional members/API keys.
get_project_credit_usage	8	None	Project credit usage history.
get_data_sources	5	None	Project data sources and sync status.
get_file_by_id	5	file_id	File metadata by ID.
search_files_by_name	5	name_query	File name search.
get_files_by_status	5	status	Files by processing status.
get_files_by_type	5	file_type	Files by MIME type or extension.
get_files_by_date_range	8	start_date, end_date	Files by date range.
get_file_statistics_detailed	10	None	Detailed file statistics and optional vector stats.
get_metadata_coverage	8	None	Metadata coverage summary.
get_sync_status	5	None	Source sync status.
get_project_usage_trends	10	None	Usage trend summary.
list_accessible_projects	3	None	Projects available to the API key.
get_subscription_details	4	None	Subscription details and usage.
create_file_upload	8	name, file_type	Create a file record and signed upload URL.
delete_file	10	file_id	Delete a file and associated vectors.
create_data_source	12	source_type	Create a data source.
update_data_source	10	data_source_id	Update data source settings.
delete_data_source	15	data_source_id	Delete a data source and associated records.
resync_data_source	6	data_source_id	Queue a data source resync.

Streaming RAG APIs

POST /askme

Streaming Server-Sent Events endpoint for answer generation.

Request body:

{
  "q": "What changed in the latest policy?",
  "threadId": "thread-id",
  "mode": "fast",
  "depth": 1,
  "searchMode": "focused",
  "maxDepth": 5,
  "sources": []
}

Supported mode values:

• fast
• research
• agentic

POST /mcp

Streaming endpoint used by enhanced chat. It supports advanced project-aware answers with citations, filters, graph context when enabled, and user-visible progress events.

POST /mcprag

Advanced MCP-compatible answer endpoint for tool-driven knowledge workflows. Use it when an integration needs richer reasoning, source grounding, and citation-aware responses.

File Access APIs

POST /generate-file-url

Generate a source-aware URL for viewing or downloading a file.

curl -X POST "https://api.structhub.io/generate-file-url" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
    "fileId": "FILE_ID",
    "accessType": "view",
    "durationHours": 24
  }'

GET /file-info/{file_id}

Return file metadata and access information for a project-scoped file.

App Control-Plane APIs

The Akurion web app uses authenticated operation endpoints for app behavior. These are usually called by the web client rather than by external developers.

Custom HTTP APIs

Method	Path	Purpose
POST	/stripe-webhook	Stripe billing webhook.
GET	/auth/sso/start	Start organization SSO.
GET	/auth/sso/callback	OIDC SSO callback.
POST	/auth/sso/exchange	Exchange SSO login token.
POST	/ui/assistant/:target	Authenticated UI proxy to assistant endpoints.
POST	/ui/file/:target	Authenticated UI proxy to file endpoints.
POST	/ui/developer/rest	Authenticated UI proxy to REST developer API.
POST	/ui/developer/mcp	Authenticated UI proxy to MCP server.
POST	/ui/tools/:target	Authenticated UI proxy to tool endpoints.
POST	/internal/datasource/:id/status	Internal Cloud Workflow status callback.
GET	/migrate-email	Legacy migration endpoint.

Connector OAuth routes are internal and are only documented publicly when the corresponding source type is enabled in the UI.

App Actions

Actions are authenticated mutations used by the web app:

Major action groups include API key management, file management, project and membership administration, billing, contact/demo requests, chat threads and messages, feedback, prompt playbooks, workflows, data source lifecycle actions for enabled source types, project metadata/settings, graph management, admin controls, SSO settings, organization admins, and workspace naming.

Connector-specific generated actions are intentionally omitted from public docs while those source tiles are disabled in the UI.

App Queries

Queries are authenticated read operations used by the web app:

Major query groups include project discovery, file lists, member lists, API keys, subscription details, usage and credit analytics, contact messages, chat history, prompt playbooks, workflows, workflow runs, SSO settings, organization settings, graph browser data, graph review queues, project analytics, admin dashboard data, global metadata/model config, and system health metrics.

Connector-specific generated queries are intentionally omitted from public docs while those source tiles are disabled in the UI.

Rate Limits and Credits

Each API key is subject to tenant-specific rate limits and credit availability. Tool calls publish credit usage events and responses include credit metadata where applicable.

Common error codes:

Code	Meaning
200	Successful request.
204	MCP initialized notification accepted.
400	Invalid request, missing parameter, or unsupported input.
401	Missing or invalid API key.
403	Valid key but forbidden project or user context.
404	Unknown route, unsupported REST operation, or missing resource.
429	Rate limit exceeded.
500	Tool execution or internal server error.