Logo
Search
Docs

Document share invite

POST https://app.sulus.ai/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/invite

Share a document with one email address

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Path parameters

knowledge_base string Required

The library.

Validation: the library's UUID
Stored in knowledge_bases.id
article string Required

The document.

Validation: the document's UUID
Stored in knowledge_articles.id

Request body

email string Required

Recipient email — there is no picker of existing users.

Validation: required|string|email|max:255
can_view boolean Optional

Optional — not required or nullable, but must be boolean when present.

Validation: boolean
can_edit boolean Optional

Optional — not required or nullable, but must be boolean when present.

Validation: boolean

Errors

StatusMeaningBody
404 Document not found, or it does not belong to that library {"message":"No query results for model [App\\Models\\KnowledgeArticle] <id>."}
403 Policy denied — outside your organization, or you cannot write to this resource {"message":"This action is unauthorized."}
422 Email belongs to the library owner already {"message":"This person already owns the document."}
422 Invalid email, sharing with yourself, or neither permission granted {"message":"…"}
422 Validation failed {"message":"…","errors":{"field":["…"]}}
401 Missing or invalid bearer token
403 Feature knowledge_docs not enabled for the account

Notes

  • can_edit implies can_view even if can_view is omitted or false; at least one of the two must end up true or the request is rejected.
  • An email that already has an account in the same organization is attached immediately (data.status is "shared", carrying the recipient's id/name/email/permissions) and notified by email. An unrecognised email instead gets a sign-up invite (data.status is "invited", carrying only email/can_view/can_edit) and is attached automatically the moment they register — the response message differs accordingly: "Invite sent to {email} — they'll get access once they create an account."
curl --request POST \
  --url https://app.sulus.ai/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/invite \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "can_view": true,
  "can_edit": false
}'
import requests

url = "https://app.sulus.ai/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/invite"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "email": "[email protected]",
  "can_view": true,
  "can_edit": false
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://app.sulus.ai/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/invite"
	payload := strings.NewReader(`{
  "email": "[email protected]",
  "can_view": true,
  "can_edit": false
}`)
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 200 
{
    "message": "Document shared — they've been emailed a link.",
    "data": {
        "status": "shared",
        "shared": {
            "id": 7,
            "name": "John Doe",
            "email": "[email protected]",
            "can_view": true,
            "can_edit": false
        }
    }
}