Give your AI agent a key, not your password.

1. Issue a key

Go to Agent keys, name it after the agent that will hold it, tick only the scopes it needs, and set an expiry. The key is shown once, so copy it straight away.

kg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Pick scopes

Scopes only ever narrow what you can already do. An agent can never reach a document you cannot reach yourself.

• READRead documents, including their contents.Safe. Start here.
• WRITECreate documents and edit their text.Cannot change who can see anything.
• SHAREChange visibility and invite people.The dangerous one. Grant only if you mean it.
• DELETEMove documents to the trash.Recoverable for 30 days.

SHARE is never implied by WRITE. An agent that can write your documents still cannot publish them to the open web unless you explicitly allow it.

3. Use the API

Send the key as a bearer token. That is the whole integration, no SDK, no OAuth dance.

Create a page

curl -X POST https://kagoj.app/api/v1/documents \
  -H "Authorization: Bearer $KAGOJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "MARKDOWN",
    "title": "Build notes",
    "source": "# Build notes\n\nAll green."
  }'

Returns { id, shortCode, url, title, visibility }. New pages default to link-only.

List what the key can read

curl https://kagoj.app/api/v1/documents \
  -H "Authorization: Bearer $KAGOJ_KEY"

Read one, with its contents

curl https://kagoj.app/api/v1/documents/{id} \
  -H "Authorization: Bearer $KAGOJ_KEY"

Text kinds return their content; a PDF, image or video returns a short-lived download link instead. Needs READ.

Edit the text

curl -X PATCH https://kagoj.app/api/v1/documents/{id} \
  -H "Authorization: Bearer $KAGOJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "# Build notes\n\nNow with a fix." }'

Needs WRITE. Text kinds only, a binary is replaced from its page, not edited.

Re-share it

curl -X PATCH https://kagoj.app/api/v1/documents/{id} \
  -H "Authorization: Bearer $KAGOJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "PUBLIC" }'

Needs SHARE, separately from WRITE. You can send source and visibility in one PATCH; each is authorised on its own.

Delete it

curl -X DELETE https://kagoj.app/api/v1/documents/{id} \
  -H "Authorization: Bearer $KAGOJ_KEY"

Needs DELETE. Moves it to the trash, where it is recoverable for 30 days.

Give it to a coding agent

Put the key in the agent’s environment and tell it the base URL. For a terminal agent, an env var is usually enough:

export KAGOJ_KEY="kg_live_..."
export KAGOJ_API="https://kagoj.app/api/v1"

There is also a machine-readable summary of Kagoj at /llms.txt that you can point an agent at.

4. Watch what it did

Every agent action is attributed to the key that performed it and listed on the Agent keys page. If something looks wrong, revoke the key, the next request it makes fails immediately.