Skip to content

API Tara: knowledge ​

Knowledge base: knowledge spaces, documents, hybrid search (MCP at /mcp/knowledge)

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/knowledge/spaces

Knowledge spaces I can read

Spaces of my current organization (any role). canWrite tells whether I can ingest documents (organization member).

Responses ​

CodeDescriptionType
200List of spacesapplication/json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "slug": "string",
      "name": "string",
      "description": "string",
      "org": "string",
      "project": "string",
      "documents": 0,
      "canWrite": false,
      "createdAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/knowledge/spaces

Create a knowledge space in my organization (organization member)

Body (application/json) ​

FieldTypeRequiredDescription
slugstringyes
namestringyes
descriptionstring
projectstring

Responses ​

CodeDescriptionType
201Createdapplication/json · object
400Invalid input (space code)application/problem+json · object
401Not signed inapplication/problem+json · object
403No permission in this organizationapplication/problem+json · object
409Space code already in useapplication/problem+json · object

Example response ​

json
{
  "slug": "string",
  "name": "string",
  "description": "string",
  "org": "string",
  "project": "string",
  "documents": 0,
  "canWrite": false,
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
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"}'
GET/v1/knowledge/sources

GitHub 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 ​

CodeDescriptionType
200Sourcesapplication/json · object
401Not signed inapplication/problem+json · object
403Owners and admins onlyapplication/problem+json · object
404No organizationapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "provider": "github",
      "host": "string",
      "repo": "string",
      "space": "string",
      "private": false,
      "defaultBranch": "string",
      "include": [],
      "status": "string",
      "documents": 0,
      "htmlUrl": "string"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/knowledge/sources" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/knowledge/sources

Attach 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) ​

FieldTypeRequiredDescription
repostringyesowner/name of a repository in the organization's GitHub installation, or the path (or URL) of a project inside the connected GitLab group
providergithub | gitlabInferred when omitted: a non-GitHub URL or a path with three or more segments is GitLab
hoststringGitLab only: must equal the base URL of the organization's GitLab connection; empty means that host
includestring[]Glob patterns of files to read; empty means the defaults

Responses ​

CodeDescriptionType
201Attachedapplication/json · object
400Invalid repository or patternapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Owners and admins signed in to the Portal or CLI onlyapplication/problem+json · object
404GitHub 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
409Already a source (source_exists) or installation suspendedapplication/problem+json · object

Example response ​

json
{
  "provider": "github",
  "host": "string",
  "repo": "string",
  "space": "string",
  "private": false,
  "defaultBranch": "string",
  "include": [
    "string"
  ],
  "status": "string",
  "documents": 0,
  "htmlUrl": "string"
}

Call with curl ​

bash
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"]}'
DELETE/v1/knowledge/source

Remove 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 ​

NameInTypeRequiredDescription
providerquerygithub | gitlabInferred like when attaching
hostquerystringGitLab base URL; must be the connection's host (default)
repoquerystringyesowner/name (GitHub) or the full project path (GitLab)

Responses ​

CodeDescriptionType
204Removed
401Not signed inapplication/problem+json · object
403Owners and admins signed in to the Portal or CLI onlyapplication/problem+json · object
404Not a source of this organizationapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/source?repo=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/knowledge/source/sync

Sync 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 ​

NameInTypeRequiredDescription
providerquerygithub | gitlabInferred like when attaching
hostquerystringGitLab base URL; must be the connection's host (default)
repoquerystringyesowner/name (GitHub) or the full project path (GitLab)

Responses ​

CodeDescriptionType
202Sync startedapplication/json · object
401Not signed inapplication/problem+json · object
403Owners and admins signed in to the Portal or CLI onlyapplication/problem+json · object
404Not a source of this organizationapplication/problem+json · object
409Already syncing (sync_running)application/problem+json · object

Example response ​

json
{
  "provider": "github",
  "host": "string",
  "repo": "string",
  "space": "string",
  "private": false,
  "defaultBranch": "string",
  "include": [
    "string"
  ],
  "status": "string",
  "documents": 0,
  "htmlUrl": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/source/sync?repo=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
DELETE/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 ​

NameInTypeRequiredDescription
ownerpathstringyes
namepathstringyes

Responses ​

CodeDescriptionType
204Removed
401Not signed inapplication/problem+json · object
403Owners and admins signed in to the Portal or CLI onlyapplication/problem+json · object
404Not a source of this organizationapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/sources/<owner>/<name>" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/knowledge/sources/{owner}/{name}/sync

Sync 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 ​

NameInTypeRequiredDescription
ownerpathstringyes
namepathstringyes

Responses ​

CodeDescriptionType
202Sync startedapplication/json · object
401Not signed inapplication/problem+json · object
403Owners and admins signed in to the Portal or CLI onlyapplication/problem+json · object
404Not a source of this organizationapplication/problem+json · object
409Already syncing (sync_running)application/problem+json · object

Example response ​

json
{
  "provider": "github",
  "host": "string",
  "repo": "string",
  "space": "string",
  "private": false,
  "defaultBranch": "string",
  "include": [
    "string"
  ],
  "status": "string",
  "documents": 0,
  "htmlUrl": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/knowledge/sources/<owner>/<name>/sync" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/knowledge/spaces/{slug}/documents

Documents ingested in a space

Parameters ​

NameInTypeRequiredDescription
slugpathstringyes

Responses ​

CodeDescriptionType
200List of documents (without content)application/json · object
401Not signed inapplication/problem+json · object
404This space is not in your scopeapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "path": "string",
      "title": "string",
      "repo": "string",
      "commit": "string",
      "version": 0,
      "chunks": 0,
      "embedded": 0,
      "updatedAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/documents" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/knowledge/spaces/{slug}/documents

Ingest 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 ​

NameInTypeRequiredDescription
slugpathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
documentsobject[]yes

Responses ​

CodeDescriptionType
200Result for each documentapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403You can read the space but cannot write to itapplication/problem+json · object
404This space is not in your scopeapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "path": "string",
      "status": "created",
      "version": 0,
      "chunks": 0,
      "embedded": 0
    }
  ],
  "warning": "string"
}

Call with curl ​

bash
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"}]}'
DELETE/v1/knowledge/spaces/{slug}/documents

Delete documents by source path (organization member)

Parameters ​

NameInTypeRequiredDescription
slugpathstringyes
pathquerystring[]yesSource path; repeat the parameter to delete several documents

Responses ​

CodeDescriptionType
200Paths that were deletedapplication/json · object
400Invalid pathapplication/problem+json · object
401Not signed inapplication/problem+json · object
403You can read the space but cannot write to itapplication/problem+json · object
404Space or document not foundapplication/problem+json · object

Example response ​

json
{
  "removed": [
    "string"
  ]
}

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/documents?path=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/knowledge/spaces/{slug}/document

Read a document verbatim

Parameters ​

NameInTypeRequiredDescription
slugpathstringyes
pathquerystringyesSource path

Responses ​

CodeDescriptionType
200Documentapplication/json · object + object
400Invalid pathapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Space or document not foundapplication/problem+json · object

Example response ​

json
{
  "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 ​

bash
curl "https://tara.phillipcli.cloud/v1/knowledge/spaces/<slug>/document?path=string" \
  -H "Authorization: Bearer $TARA_TOKEN"