Share Knowledge base access

Grant, change, or revoke Knowledge base access for people and workspace API keys

Grants, changes, or revokes access on an existing Knowledge base. Targets are people and workspace API keys. Groups stay on the in-app Share Knowledge bases with the API flow.

Before You Start

API key scope: Requires an API key with the KNOWLEDGE_FOLDER_API scope. The API key itself needs the Editor role on the Knowledge base. See Share Knowledge bases with the API for setup instructions.
Knowledge bases: The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

Base URL

https://api.ajan.io

Roles

API value	Library label	Access
`USER`	Viewer	Search and retrieve files
`EDITOR`	Editor	Upload, update, delete, share access, and rename

A Viewer-only key, including a key that only has API search through the Knowledge base, cannot call these endpoints.

An Editor workspace key can grant other qualifying workspace keys even if the key owner is not a workspace admin. The in-app Share dialog still lists API keys only for workspace admins.

Grant access

POST /knowledge/{folderId}/access

Path Parameters

Parameter	Type	Required	Description
`folderId`	string	Yes	The ID of the Knowledge base

Request Body

Field	Type	Required	Description
`targetIds`	string\[]	Yes	User IDs and workspace API key IDs to grant. Minimum: `1`. Maximum: `100`.
`role`	string	Yes	`USER` or `EDITOR`

All IDs must resolve to a human workspace member or a qualifying workspace API key. Group IDs are not accepted. Personal API keys are not eligible. If any ID is missing or ineligible, the request fails and no grants are written.

Grant with cURL

bash

curl -X POST "https://api.ajan.io/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "role": "EDITOR"
  }'

Grant with JavaScript

javascript

const axios = require("axios");

async function grantAccess(folderId, targetIds, role) {
  const response = await axios.post(
    `https://api.ajan.io/knowledge/${folderId}/access`,
    { targetIds, role },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  return response.data;
}

const result = await grantAccess(
  "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
  "EDITOR"
);
console.log(result.result.granted);

Success Response (200 OK)

json

{
  "status": "success",
  "result": {
    "granted": [
      {
        "type": "USER",
        "targetId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "role": "EDITOR"
      },
      {
        "type": "API_KEY",
        "targetId": "550e8400-e29b-41d4-a716-446655440000",
        "role": "EDITOR"
      }
    ]
  }
}

Change a role

PATCH /knowledge/{folderId}/access

Field	Type	Required	Description
`type`	string	Yes	`USER` or `API_KEY`
`targetId`	string	Yes	The person or workspace API key ID
`role`	string	Yes	`USER` or `EDITOR`

You cannot change the Knowledge base owner's access. Reassign ownership in the Library first. If the target has no grant yet, this request creates one.

bash

curl -X PATCH "https://api.ajan.io/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "API_KEY",
    "targetId": "550e8400-e29b-41d4-a716-446655440000",
    "role": "USER"
  }'

json

{
  "status": "success"
}

Revoke access

DELETE /knowledge/{folderId}/access

Field	Type	Required	Description
`type`	string	Yes	`USER` or `API_KEY`
`targetId`	string	Yes	The person or workspace API key ID

You cannot revoke the Knowledge base owner's access.

bash

curl -X DELETE "https://api.ajan.io/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "API_KEY",
    "targetId": "550e8400-e29b-41d4-a716-446655440000"
  }'

json

{
  "status": "success"
}

Error Handling

Status	Meaning
`400`	Invalid body, ineligible share target, or owner access change
`401`	Invalid or missing API key
`403`	Missing `KNOWLEDGE_FOLDER_API` scope, or the key is not Editor on this Knowledge base
`404`	Knowledge base or access target not found
`429`	Rate limit exceeded
`500`	Unexpected server error

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /knowledge/{folderId}/access:
    post:
      summary: Grant Knowledge base access to people or workspace API keys
      parameters:
        - name: folderId
          in: path
          required: true
          description: The ID of the knowledge folder
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - targetIds
                - role
              properties:
                targetIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 100
                role:
                  type: string
                  enum:
                    - USER
                    - EDITOR
      responses:
        '200':
          description: Access granted successfully
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"