{"openapi":"3.1.0","info":{"title":"Dify Knowledge (BYOK) API","version":"0.1.0","description":"Dify Knowledge (BYOK) lets an AI assistant read your own Dify Knowledge data through the Dify Knowledge API with a key you supply (Dify knowledge base API key). Read-only: 10 tools (list_knowledge_bases, get_knowledge_base, list_documents, get_document, get_indexing_status, list_chunks, list_metadata_fields, list_knowledge_tags, get_knowledge_base_tags, list_available_models). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-dify-knowledge.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-dify-knowledge/docs"},"termsOfService":"https://connectorbay.com/byok-dify-knowledge/terms"},"servers":[{"url":"https://byok-dify-knowledge.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-dify-knowledge/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_knowledge_bases":{"post":{"operationId":"list_knowledge_bases","summary":"List the knowledge bases of the workspace with document counts, word counts, embedding model and indexing technique. Use","description":"List the knowledge bases of the workspace with document counts, word counts, embedding model and indexing technique. Use for \"What knowledge bases do I have in Dify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keyword":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only knowledge bases whose name contains this text.","title":"Keyword"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (the server caps this at 100).","title":"Limit"}},"title":"list_knowledge_basesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_knowledge_base":{"post":{"operationId":"get_knowledge_base","summary":"Get one knowledge base: embedding model, indexing technique, retrieval settings, tags and document statistics. Use for \"","description":"Get one knowledge base: embedding model, indexing technique, retrieval settings, tags and document statistics. Use for \"What retrieval settings does Dify knowledge base X use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"}},"required":["dataset_id"],"title":"get_knowledge_baseArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_documents":{"post":{"operationId":"list_documents","summary":"List the documents of a knowledge base with indexing status, word count, tokens, hit count and enabled flag. Use for \"Wh","description":"List the documents of a knowledge base with indexing status, word count, tokens, hit count and enabled flag. Use for \"Which documents of Dify knowledge base X failed indexing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"},"keyword":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only documents whose name contains this text.","title":"Keyword"},"status":{"anyOf":[{"enum":["queuing","indexing","paused","error","available","disabled","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Only documents with this display status.","title":"Status"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (the server caps this at 100).","title":"Limit"}},"required":["dataset_id"],"title":"list_documentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_document":{"post":{"operationId":"get_document","summary":"Get one document of a knowledge base: indexing status and latency, segment count, language, type and metadata values. Us","description":"Get one document of a knowledge base: indexing status and latency, segment count, language, type and metadata values. Use for \"How many chunks does document Y in Dify knowledge base X have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"},"document_id":{"description":"Document id, from list_documents.","maxLength":200,"title":"Document Id","type":"string"},"metadata":{"anyOf":[{"enum":["all","only","without"],"type":"string"},{"type":"null"}],"default":"all","description":"What to return: all fields, only metadata, or everything without metadata.","title":"Metadata"}},"required":["dataset_id","document_id"],"title":"get_documentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_indexing_status":{"post":{"operationId":"get_indexing_status","summary":"Show the indexing progress of the documents in one upload batch: stage and completed versus total chunks. Use for \"Has D","description":"Show the indexing progress of the documents in one upload batch: stage and completed versus total chunks. Use for \"Has Dify finished indexing batch B of knowledge base X\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"},"batch":{"description":"Batch id returned when documents were uploaded or updated.","maxLength":200,"title":"Batch","type":"string"}},"required":["dataset_id","batch"],"title":"get_indexing_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_chunks":{"post":{"operationId":"list_chunks","summary":"List the chunks (segments) of one document with content, word count, tokens, hit count, keywords and status. Use for \"Sh","description":"List the chunks (segments) of one document with content, word count, tokens, hit count, keywords and status. Use for \"Show the chunks of document Y in Dify knowledge base X\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"},"document_id":{"description":"Document id, from list_documents.","maxLength":200,"title":"Document Id","type":"string"},"keyword":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only chunks that contain this text.","title":"Keyword"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (the server caps this at 100).","title":"Limit"}},"required":["dataset_id","document_id"],"title":"list_chunksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_metadata_fields":{"post":{"operationId":"list_metadata_fields","summary":"List the metadata fields of a knowledge base (custom and built-in) with their type and how many documents use each. Use ","description":"List the metadata fields of a knowledge base (custom and built-in) with their type and how many documents use each. Use for \"What metadata fields does Dify knowledge base X define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"}},"required":["dataset_id"],"title":"list_metadata_fieldsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_knowledge_tags":{"post":{"operationId":"list_knowledge_tags","summary":"List all knowledge base tags of the workspace with the number of knowledge bases bound to each. Use for \"Which tags do m","description":"List all knowledge base tags of the workspace with the number of knowledge bases bound to each. Use for \"Which tags do my Dify knowledge bases use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_knowledge_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_knowledge_base_tags":{"post":{"operationId":"get_knowledge_base_tags","summary":"List the tags bound to one knowledge base. Use for \"Which tags does Dify knowledge base X have\".","description":"List the tags bound to one knowledge base. Use for \"Which tags does Dify knowledge base X have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Knowledge base id, from list_knowledge_bases.","maxLength":200,"title":"Dataset Id","type":"string"}},"required":["dataset_id"],"title":"get_knowledge_base_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_available_models":{"post":{"operationId":"list_available_models","summary":"List the models of a type configured in the workspace (for example text embedding or rerank models) with provider and st","description":"List the models of a type configured in the workspace (for example text embedding or rerank models) with provider and status. Use for \"Which embedding models can I use in my Dify workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"model_type":{"description":"Kind of model: text-embedding, rerank, llm, tts, speech2text or moderation.","enum":["text-embedding","rerank","llm","tts","speech2text","moderation"],"title":"Model Type","type":"string"}},"required":["model_type"],"title":"list_available_modelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}