v1REST API

Knowledge Base Management API

Create, manage, and query knowledge bases programmatically. Add sources, configure sync schedules, and toggle settings — all via API.

Overview

The Akyn API lets you manage knowledge bases without the dashboard. All endpoints live under /api/v1/ and use your existing API key for authentication.

Base URL: https://akyn.dev/api/v1

Content-Type: application/json

Auth: Authorization: Bearer ak_...

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer ak_your_api_key_here

API keys are created in Dashboard → Settings. Each key has a permission level:

Query only

Can list KBs, list sources, and query. Cannot create, update, or delete.

Full access

All query permissions plus creating, updating, and deleting KBs and sources.

Tip: You can use the same API key for both MCP connections and this management API. Use "Query only" keys for MCP clients and "Full access" keys for automation.

Rate Limits

Each API key has a configurable rate limit (default: 60 requests per minute). When exceeded, the API responds with 429 Too Many Requests.

X-RateLimit-Limit — Maximum requests per window

X-RateLimit-Remaining — Remaining requests

Retry-After — Seconds until the window resets

Error Handling

All errors return a JSON body with an error field.

Status	Meaning
400	Bad request (invalid or missing fields)
401	Missing or invalid API key
403	Insufficient permissions (need "manage")
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Knowledge Bases

Create and manage private knowledge bases.

GET/api/v1/knowledge-bases

List all knowledge bases owned by the authenticated user.

Query or Full access

Example

curl https://akyn.dev/api/v1/knowledge-bases \
  -H "Authorization: Bearer ak_your_key"

Response

{
  "knowledge_bases": [
    {
      "id": "9aeed292-...",
      "name": "My KB",
      "description": "Company docs",
      "is_public": false,
      "memory_enabled": true,
      "language": "en",
      "tags": ["docs"],
      "source_count": 5,
      "mcp_url": "https://akyn.dev/mcp/9aeed292-...",
      "created_at": "2026-01-07T17:39:22Z",
      "updated_at": "2026-04-01T18:20:06Z"
    }
  ]
}

POST/api/v1/knowledge-bases

Create a new private knowledge base.

Full access required

Request body

Field	Type	Required	Description
name	string	Yes	Name of the knowledge base
description	string	No	Description
language	string	No	Language code (e.g. "en")
tags	string[]	No	Tags for categorization
memory_enabled	boolean	No	Enable memory (default: true)

Example

curl -X POST https://akyn.dev/api/v1/knowledge-bases \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Docs",
    "description": "Internal documentation",
    "language": "en",
    "tags": ["internal", "docs"],
    "memory_enabled": true
  }'

Response 201

{
  "knowledge_base": {
    "id": "264b337a-...",
    "name": "Company Docs",
    "description": "Internal documentation",
    "is_public": false,
    "memory_enabled": true,
    "language": "en",
    "tags": ["internal", "docs"],
    "mcp_url": "https://akyn.dev/mcp/264b337a-...",
    "created_at": "2026-04-03T17:21:07Z",
    "updated_at": "2026-04-03T17:21:07Z"
  }
}

The response includes mcp_url — use this to connect AI clients to your new KB immediately.

GET/api/v1/knowledge-bases/:id

Get details of a specific knowledge base.

Query or Full access

curl https://akyn.dev/api/v1/knowledge-bases/264b337a-... \
  -H "Authorization: Bearer ak_your_key"

PATCH/api/v1/knowledge-bases/:id

Update name, description, language, or tags.

Full access required

curl -X PATCH https://akyn.dev/api/v1/knowledge-bases/264b337a-... \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "tags": ["new-tag"]}'

DELETE/api/v1/knowledge-bases/:id

Permanently delete a knowledge base and all its data (sources, embeddings, memories).

Full access required

curl -X DELETE https://akyn.dev/api/v1/knowledge-bases/264b337a-... \
  -H "Authorization: Bearer ak_your_key"

Response

{ "success": true }

PATCH/api/v1/knowledge-bases/:id/settings

Update KB settings like memory, name, description, language, and tags.

Full access required

curl -X PATCH https://akyn.dev/api/v1/knowledge-bases/264b337a-.../settings \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"memory_enabled": false}'

Sources

Add, list, and remove data sources. Sources are processed automatically after creation.

GET/api/v1/knowledge-bases/:id/sources

List all sources for a knowledge base.

Query or Full access

curl https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources \
  -H "Authorization: Bearer ak_your_key"

Response

{
  "sources": [
    {
      "id": "6979eeb4-...",
      "source_type": "url",
      "source_name": "docs.example.com",
      "source_url": "https://docs.example.com",
      "status": "completed",
      "sync_frequency": "daily",
      "sync_time": "09:00:00",
      "next_sync_at": "2026-04-04T07:00:00Z",
      "last_synced_at": "2026-04-03T07:00:12Z",
      "created_at": "2026-04-03T17:22:22Z"
    }
  ]
}

POST/api/v1/knowledge-bases/:id/sources

Add a URL source. Content is fetched and processed automatically.

Full access required

URL source

Field	Type	Required	Description
type	string	Yes	Must be `"url"`
url	string	Yes	The URL to ingest
sync_frequency	string	No	`never`, `hourly`, `daily`, or `weekly`
sync_time	string	No	Time of day for sync (e.g. `"09:00"`)
sync_day_of_week	number	No	Day for weekly sync (0=Sun, 6=Sat)

curl -X POST https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://docs.example.com/guide",
    "sync_frequency": "daily",
    "sync_time": "09:00"
  }'

POST/api/v1/knowledge-bases/:id/sources

Add a file source by providing a publicly accessible URL to the file.

Full access required

File source

Field	Type	Required	Description
type	string	Yes	Must be `"file"`
file_url	string	Yes	Public URL to the file
file_name	string	No	Filename (inferred from URL if omitted)

Supported file types: pdf, txt, md, docx. Max size: 50 MB.

curl -X POST https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_url": "https://example.com/reports/q1-2026.pdf",
    "file_name": "q1-2026.pdf"
  }'

GET/api/v1/knowledge-bases/:id/sources/:sourceId

Get details of a specific source, including processing status and sync info.

Query or Full access

curl https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources/6979eeb4-... \
  -H "Authorization: Bearer ak_your_key"

DELETE/api/v1/knowledge-bases/:id/sources/:sourceId

Delete a source and its embeddings.

Full access required

curl -X DELETE https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources/6979eeb4-... \
  -H "Authorization: Bearer ak_your_key"

PATCH/api/v1/knowledge-bases/:id/sources/:sourceId/sync

Update the sync frequency for a URL, Notion, or Google Drive source.

Full access required

Field	Type	Description
sync_frequency	string	`never`, `hourly`, `daily`, or `weekly`
sync_time	string	Time of day (e.g. `"09:00"`)
sync_day_of_week	number	Day for weekly (0=Sun, 6=Sat)

curl -X PATCH https://akyn.dev/api/v1/knowledge-bases/264b337a-.../sources/6979eeb4-.../sync \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sync_frequency": "weekly", "sync_time": "10:00", "sync_day_of_week": 1}'

Query

Search your knowledge base with semantic queries. Results are reranked for relevance.

POST/api/query

Semantic search across a knowledge base. Returns the most relevant chunks with similarity scores.

Query or Full access

Field	Type	Required	Description
knowledgeBaseId	string	Yes	ID of the knowledge base to query
query	string	Yes	Your search question

curl -X POST https://akyn.dev/api/query \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "9aeed292-...",
    "query": "What is the return policy?"
  }'

Response

{
  "results": [
    {
      "id": "chunk-uuid",
      "chunk_text": "Our return policy allows...",
      "similarity": 0.93,
      "metadata": {
        "source_name": "policies.pdf",
        "source_id": "...",
        "chunk_index": 3
      }
    }
  ],
  "tokenCount": 5,
  "responseTimeMs": 245,
  "reranked": true,
  "billing": { "charged": 0.015 }
}