API Tara: knowledge
Knowledge base: knowledge spaces, documents, hybrid search (MCP at /mcp/knowledge)
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/knowledge/spacesKnowledge spaces I can read
Spaces of my current organization (any role). canWrite tells whether I can ingest documents (organization member).
Responses
| Code | Description | Type |
|---|---|---|
| 200 | List of spaces | application/json · object |
| 401 | Not signed in | application/problem+json · object |
Example response
{
"items": [
{
"slug": "string",
"name": "string",
"description": "string",
"org": "string",
"project": "string",
"documents": 0,
"canWrite": false,
"createdAt": "2026-11-01T00:00:00Z"
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/spacesCreate a knowledge space in my organization (organization member)
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
name | string | yes | |
description | string | ||
project | string |
Responses
| Code | Description | Type |
|---|---|---|
| 201 | Created | application/json · object |
| 400 | Invalid input (space code) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | No permission in this organization | application/problem+json · object |
| 409 | Space code already in use | application/problem+json · object |
Example response
{
"slug": "string",
"name": "string",
"description": "string",
"org": "string",
"project": "string",
"documents": 0,
"canWrite": false,
"createdAt": "2026-11-01T00:00:00Z"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/spaces" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"slug":"string","name":"string","description":"string","project":"string"}'/v1/knowledge/sourcesGitHub and GitLab repositories attached as knowledge sources (owner or admin)
Every repository of the organization's GitHub App installation or connected GitLab group that an owner or admin attached as a knowledge source, with its sync status. Each source has its own space (gh-<owner>-<repo> or gl-<group>-<project>). Members see the spaces they may read, with the status, in GET /v1/knowledge/spaces.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Sources | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins only | application/problem+json · object |
| 404 | No organization | application/problem+json · object |
Example response
{
"items": [
{
"provider": "github",
"host": "string",
"repo": "string",
"space": "string",
"private": false,
"defaultBranch": "string",
"include": [],
"status": "string",
"documents": 0,
"htmlUrl": "string"
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/knowledge/sources" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/sourcesAttach a repository of the GitHub App installation or the connected GitLab group as a knowledge source (owner or admin, session only)
provider picks github or gitlab; when omitted it is inferred (a URL that is not GitHub, or a path with three or more segments, means GitLab; anything else GitHub). A GitLab repository must be inside the group of the organization's GitLab connection (GET /v1/orgs/{org}/gitlab) and on its host: the host is never taken from the request to call out, only compared with the connection's. Creates a space for the repository and starts the first sync in the background (status is syncing; poll the list). Only markdown and text files that match include are read, at most 1000 files, 2 MiB each. Access follows each person's own GitHub permission. Documents of a private repository are visible only to members whose linked GitHub account has at least read permission on the repository (checked with the installation token, cached 10 minutes; members with no linked GitHub account, or when GitHub cannot be reached, see nothing). Documents of a public repository are visible to every member. Nothing is visible outside the organization. GitLab follows the same rule with the GitLab identity (the member signed in to Tara with GitLab on the same host) and the project membership (Reporter or higher, including access inherited from the group), asked with the connection's credential.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repo | string | yes | owner/name of a repository in the organization's GitHub installation, or the path (or URL) of a project inside the connected GitLab group |
provider | github | gitlab | Inferred when omitted: a non-GitHub URL or a path with three or more segments is GitLab | |
host | string | GitLab only: must equal the base URL of the organization's GitLab connection; empty means that host | |
include | string[] | Glob patterns of files to read; empty means the defaults |
Responses
| Code | Description | Type |
|---|---|---|
| 201 | Attached | application/json · object |
| 400 | Invalid repository or pattern | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins signed in to the Portal or CLI only | application/problem+json · object |
| 404 | GitHub not linked (github_not_linked) or repository not in the installation (repo_not_in_installation); GitLab not connected (gitlab_not_connected) or repository not in the group (repo_not_in_group) | application/problem+json · object |
| 409 | Already a source (source_exists) or installation suspended | application/problem+json · object |
Example response
{
"provider": "github",
"host": "string",
"repo": "string",
"space": "string",
"private": false,
"defaultBranch": "string",
"include": [
"string"
],
"status": "string",
"documents": 0,
"htmlUrl": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/sources" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repo":"acme/shop-web","provider":"github","host":"string","include":["string"]}'/v1/knowledge/sourceRemove a GitHub or GitLab knowledge source by repository (owner or admin, session only)
Same as DELETE /v1/knowledge/sources/{owner}/{name} but takes the repository as a query parameter, so GitLab paths with subgroups (group/sub/project) work.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | query | github | gitlab | Inferred like when attaching | |
host | query | string | GitLab base URL; must be the connection's host (default) | |
repo | query | string | yes | owner/name (GitHub) or the full project path (GitLab) |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Removed | |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins signed in to the Portal or CLI only | application/problem+json · object |
| 404 | Not a source of this organization | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/source?repo=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/source/syncSync a GitHub or GitLab knowledge source now by repository (owner or admin, session only)
Same as POST /v1/knowledge/sources/{owner}/{name}/sync but takes the repository as a query parameter, so GitLab paths with subgroups work. A GitLab source also syncs on a push to the default branch (project or group webhook of the GitLab connection) and periodically.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | query | github | gitlab | Inferred like when attaching | |
host | query | string | GitLab base URL; must be the connection's host (default) | |
repo | query | string | yes | owner/name (GitHub) or the full project path (GitLab) |
Responses
| Code | Description | Type |
|---|---|---|
| 202 | Sync started | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins signed in to the Portal or CLI only | application/problem+json · object |
| 404 | Not a source of this organization | application/problem+json · object |
| 409 | Already syncing (sync_running) | application/problem+json · object |
Example response
{
"provider": "github",
"host": "string",
"repo": "string",
"space": "string",
"private": false,
"defaultBranch": "string",
"include": [
"string"
],
"status": "string",
"documents": 0,
"htmlUrl": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/source/sync?repo=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/sources/{owner}/{name}Remove a GitHub knowledge source (owner or admin, session only)
Deletes the space of the repository with every document and chunk synced from it. The repository itself is untouched.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
name | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Removed | |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins signed in to the Portal or CLI only | application/problem+json · object |
| 404 | Not a source of this organization | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/sources/<owner>/<name>" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/sources/{owner}/{name}/syncSync a GitHub knowledge source now (owner or admin, session only)
Fetches the default branch at its current commit, re-reads only the files whose content changed and deletes the ones that left the repository. Runs in the background: the answer carries status: syncing. The repository also syncs on every push to its default branch (GitHub push webhook) and periodically.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
name | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 202 | Sync started | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Owners and admins signed in to the Portal or CLI only | application/problem+json · object |
| 404 | Not a source of this organization | application/problem+json · object |
| 409 | Already syncing (sync_running) | application/problem+json · object |
Example response
{
"provider": "github",
"host": "string",
"repo": "string",
"space": "string",
"private": false,
"defaultBranch": "string",
"include": [
"string"
],
"status": "string",
"documents": 0,
"htmlUrl": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/sources/<owner>/<name>/sync" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/spaces/{slug}/documentsDocuments ingested in a space
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | List of documents (without content) | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | This space is not in your scope | application/problem+json · object |
Example response
{
"items": [
{
"path": "string",
"title": "string",
"repo": "string",
"commit": "string",
"version": 0,
"chunks": 0,
"embedded": 0,
"updatedAt": "2026-11-01T00:00:00Z"
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/documents" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/spaces/{slug}/documentsIngest or replace documents by source path (organization member)
Each document is UTF-8 markdown/text, split into chunks by heading. The source path is the key: if it exists, the version is replaced (identical content does nothing except update repo and commit). The whole batch is validated before writing. If embedding is configured, chunks get vectors; an embedding failure does not block ingestion (the chunks can only be found by full-text, and warning says so). Up to 200 documents per call, each up to 2 MiB.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
documents | object[] | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Result for each document | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | You can read the space but cannot write to it | application/problem+json · object |
| 404 | This space is not in your scope | application/problem+json · object |
Example response
{
"items": [
{
"path": "string",
"status": "created",
"version": 0,
"chunks": 0,
"embedded": 0
}
],
"warning": "string"
}Call with curl
curl -X PUT "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/documents" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"documents":[{"path":"string","title":"string","content":"string","repo":"string"}]}'/v1/knowledge/spaces/{slug}/documentsDelete documents by source path (organization member)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | |
path | query | string[] | yes | Source path; repeat the parameter to delete several documents |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Paths that were deleted | application/json · object |
| 400 | Invalid path | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | You can read the space but cannot write to it | application/problem+json · object |
| 404 | Space or document not found | application/problem+json · object |
Example response
{
"removed": [
"string"
]
}Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/documents?path=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/spaces/{slug}/documentRead a document verbatim
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | |
path | query | string | yes | Source path |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Document | application/json · object + object |
| 400 | Invalid path | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Space or document not found | application/problem+json · object |
Example response
{
"path": "string",
"title": "string",
"repo": "string",
"commit": "string",
"version": 0,
"chunks": 0,
"embedded": 0,
"updatedAt": "2026-11-01T00:00:00Z",
"space": "string",
"content": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/document?path=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/knowledge/searchHybrid search (full-text + business codes + vectors when embedding is on) in the spaces I can read
Filtered by permission before ranking. Results are merged with reciprocal rank fusion, and each chunk carries its source for citation (repo, commit, path, heading). mode is hybrid when vectors are also used, fulltext when not.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | yes | |
space | query | string | Search only in this space | |
topK | query | integer |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Chunks found | application/json · object |
| 400 | Missing query | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | This space is not in your scope | application/problem+json · object |
Example response
{
"hits": [
{
"space": "string",
"path": "string",
"title": "string",
"repo": "string",
"commit": "string",
"heading": "string",
"text": "string",
"score": 0,
"citation": "string"
}
],
"mode": "hybrid",
"warning": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/knowledge/search?q=string" \
-H "Authorization: Bearer $TARA_TOKEN"