Dify Knowledge Retrieval

curl --request POST \
  --url https://api.example.com/api/knowledge-retrieval/dify/retrieval \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledge_id": "<string>",
  "query": "<string>",
  "retrieval_setting": {
    "top_k": 123,
    "score_threshold": 123
  },
  "metadata_condition": {
    "logical_operator": "<string>",
    "conditions": [
      {
        "name": [
          {}
        ],
        "comparison_operator": "<string>",
        "value": "<string>"
      }
    ]
  }
}
'

{
  "records": [
    {
      "content": "<string>",
      "score": 123,
      "title": "<string>",
      "metadata": {
        "path": "<string>",
        "file_extension": "<string>",
        "data_source_id": "<string>",
        "data_source_name": "<string>",
        "data_source_type": "<string>",
        "artifact_kind": "<string>",
        "start_line": 123,
        "end_line": 123
      }
    }
  ]
}

POST

api

knowledge-retrieval

dify

retrieval

Dify Knowledge Retrieval

curl --request POST \
  --url https://api.example.com/api/knowledge-retrieval/dify/retrieval \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledge_id": "<string>",
  "query": "<string>",
  "retrieval_setting": {
    "top_k": 123,
    "score_threshold": 123
  },
  "metadata_condition": {
    "logical_operator": "<string>",
    "conditions": [
      {
        "name": [
          {}
        ],
        "comparison_operator": "<string>",
        "value": "<string>"
      }
    ]
  }
}
'

{
  "records": [
    {
      "content": "<string>",
      "score": 123,
      "title": "<string>",
      "metadata": {
        "path": "<string>",
        "file_extension": "<string>",
        "data_source_id": "<string>",
        "data_source_name": "<string>",
        "data_source_type": "<string>",
        "artifact_kind": "<string>",
        "start_line": 123,
        "end_line": 123
      }
    }
  ]
}

Overview

This endpoint implements the Dify External Knowledge API specification, allowing Dify AI applications to query CodeAlive repositories and workspaces as knowledge bases. Use this endpoint to integrate CodeAlive’s code search capabilities into your Dify workflows and AI agents.

Finding the knowledge_id

The knowledge_id must be the ID of a repository or workspace from your CodeAlive account. You can copy the ID from the CodeAlive UI:

For repositories: Go to Repositories page, click the copy button next to the repository
For workspaces: Go to Workspaces page, click the copy button next to the workspace

Request

knowledge_id

string

required

The ID of the repository or workspace to search (e.g., "67f664fd4c2a00698a52bb6f")

query

string

required

The search query describing what code or information you’re looking for

retrieval_setting

object

Settings for the retrieval operation

Show Retrieval Setting Object

top_k

number

default:"5"

Maximum number of results to return (typically 1-20)

score_threshold

number

default:"0.7"

Minimum relevance score threshold (0.0-1.0). Results below this score will be filtered out.

metadata_condition

object

Optional metadata filtering conditions

Show Metadata Condition Object

logical_operator

string

Logical operator for combining conditions: "and" or "or"

conditions

array

Array of filter conditions

Show Condition Object

name

array

Array with a single metadata field name (e.g., ["file_extension"])

comparison_operator

string

Comparison operator: "is", "is_not", "contains", "not_contains"

value

string

Value to compare against (e.g., ".cs", ".js")

Response

records

array

Array of search result records

Show Record Object

content

string

The code content of the found artifact

score

number

Relevance score (0.0-1.0, higher is more relevant)

title

string

Title of the artifact (typically the file name)

metadata

object

Additional metadata about the result

Show Metadata Object

path

string

File path relative to repository root

file_extension

string

File extension (e.g., ".cs", ".js")

data_source_id

string

ID of the data source (repository or workspace)

data_source_name

string

Name of the data source

data_source_type

string

Type: "repository" or "workspace"

artifact_kind

string

Kind of artifact (e.g., "symbol", "class", "function", "chunk")

start_line

number

Starting line number

end_line

number

Ending line number

Code Examples

import requests

url = "https://app.codealive.ai/api/knowledge-retrieval/dify/retrieval"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "knowledge_id": "67f664fd4c2a00698a52bb6f",
    "query": "authentication implementation",
    "retrieval_setting": {
        "top_k": 5,
        "score_threshold": 0.7
    },
    "metadata_condition": {
        "logical_operator": "and",
        "conditions": [
            {
                "name": ["file_extension"],
                "comparison_operator": "is",
                "value": ".cs"
            }
        ]
    }
}

response = requests.post(url, headers=headers, json=data)
results = response.json()

for record in results["records"]:
    print(f"Score: {record['score']}")
    print(f"File: {record['title']}")
    print(f"Content preview: {record['content'][:100]}...")
    print("---")

Example Response

{
  "records": [
    {
      "content": "public class AuthenticationService : IAuthService\n{\n    private readonly ITokenGenerator _tokenGenerator;\n    // ... implementation\n}",
      "score": 0.95,
      "title": "AuthenticationService.cs",
      "metadata": {
        "path": "src/Services/AuthenticationService.cs",
        "file_extension": ".cs",
        "data_source_id": "67f664fd4c2a00698a52bb6f",
        "data_source_name": "My Repository",
        "data_source_type": "repository",
        "artifact_kind": "symbol",
        "start_line": 15,
        "end_line": 28
      }
    },
    {
      "content": "public class LoginRequest\n{\n    public string Username { get; set; }\n    public string Password { get; set; }\n}",
      "score": 0.78,
      "title": "LoginRequest.cs",
      "metadata": {
        "path": "src/Models/LoginRequest.cs",
        "file_extension": ".cs",
        "data_source_id": "67f664fd4c2a00698a52bb6f",
        "data_source_name": "My Repository",
        "data_source_type": "repository",
        "artifact_kind": "symbol"
      }
    }
  ]
}

Filtering Examples

Filter by File Extension

Search only in C# files:

{
  "knowledge_id": "67f664fd4c2a00698a52bb6f",
  "query": "user validation",
  "metadata_condition": {
    "logical_operator": "and",
    "conditions": [
      {
        "name": ["file_extension"],
        "comparison_operator": "is",
        "value": ".cs"
      }
    ]
  }
}

Exclude Test Files

Search excluding test files:

{
  "knowledge_id": "67f664fd4c2a00698a52bb6f",
  "query": "database queries",
  "metadata_condition": {
    "logical_operator": "and",
    "conditions": [
      {
        "name": ["path"],
        "comparison_operator": "not_contains",
        "value": "test"
      }
    ]
  }
}

Multiple Conditions

Search for TypeScript files excluding tests:

{
  "knowledge_id": "67f664fd4c2a00698a52bb6f",
  "query": "API endpoints",
  "metadata_condition": {
    "logical_operator": "and",
    "conditions": [
      {
        "name": ["file_extension"],
        "comparison_operator": "is",
        "value": ".ts"
      },
      {
        "name": ["path"],
        "comparison_operator": "not_contains",
        "value": ".test."
      }
    ]
  }
}

Error Responses

400 Bad Request (Error Code 1001)

Invalid request format or validation error:

{
  "error_code": 1001,
  "error_msg": "Invalid request format. Query is required."
}

401 Unauthorized (Error Code 1004)

Authentication failed - invalid or missing API key:

{
  "error_code": 1004,
  "error_msg": "Authentication failed. Please provide a valid API key."
}

403 Forbidden (Error Code 1002)

Authorization failed - access denied to specified data source:

{
  "error_code": 1002,
  "error_msg": "Authorization failed. You don't have access to this knowledge base."
}

404 Not Found (Error Code 1003)

Knowledge base not found:

{
  "error_code": 1003,
  "error_msg": "Knowledge base not found. Please check the knowledge_id."
}

500 Internal Server Error (Error Code 2001)

Internal server error:

{
  "error_code": 2001,
  "error_msg": "An internal error occurred while processing your request."
}

Dify Integration

To use this endpoint in Dify:

In your Dify application, configure an External Knowledge Base
Set the API endpoint to https://app.codealive.ai/api/knowledge-retrieval/dify/retrieval
Add your CodeAlive API key in the Authorization header as Bearer YOUR_API_KEY
Use your repository or workspace ID as the knowledge_id

The API automatically formats responses according to Dify’s External Knowledge API specification, enabling seamless integration.

Best Practices

Optimize Retrieval Quality

Set score_threshold to 0.7-0.8 for balanced results
Use top_k between 3-10 for most use cases
Write specific, descriptive queries
Include technical terms relevant to your search

Use Metadata Filtering

Filter by file extension to focus on specific languages
Exclude test files for production code searches
Use path filters to search specific directories
Combine multiple conditions for precise results

Handle Results Effectively

Check scores to gauge result relevance
Use metadata for context about where code was found
Leverage location info (line numbers) for precise references
Process results in order of score (highest first)

Get Available Data Sources Search

​Overview

​Finding the knowledge_id

​Request

​Response

​Code Examples

​Example Response

​Filtering Examples

​Filter by File Extension

​Exclude Test Files

​Multiple Conditions

​Error Responses

​400 Bad Request (Error Code 1001)

​401 Unauthorized (Error Code 1004)

​403 Forbidden (Error Code 1002)

​404 Not Found (Error Code 1003)

​500 Internal Server Error (Error Code 2001)

​Dify Integration

​Best Practices

Overview

Finding the knowledge_id

Request

Response

Code Examples

Example Response

Filtering Examples

Filter by File Extension

Exclude Test Files

Multiple Conditions

Error Responses

400 Bad Request (Error Code 1001)

401 Unauthorized (Error Code 1004)

403 Forbidden (Error Code 1002)

404 Not Found (Error Code 1003)

500 Internal Server Error (Error Code 2001)

Dify Integration

Best Practices