First API request

This walkthrough creates /api-example/hello.md in a workspace and reads its text back. You need a Cabane account, access to a workspace, Bash and curl with --fail-with-body support.

1Create a token

In Cabane, open your avatar menu, then Your settings → API keys. Under New personal access token, enter a label and choose an expiration, then choose Create token. Copy the value while it is visible; Cabane shows it once. See Authentication for the complete token choices.

Run these commands in Bash. The prompt keeps the token out of the command itself:

CABANE_BASE='https://app.cabane.ai'
read -r -s -p 'Personal access token: ' CABANE_TOKEN
printf '\n'

Keep this terminal open for the remaining steps.

2Choose a workspace

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  "$CABANE_BASE/api/workspaces" \
  --header "Authorization: Bearer $CABANE_TOKEN"

The response contains a workspaces array. Find the workspace you want by its name and copy its id, which is a UUID. Use that value at the next prompt:

read -r -p 'Workspace id: ' CABANE_WORKSPACE_ID

3Write a file

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  "$CABANE_BASE/api/workspaces/$CABANE_WORKSPACE_ID/ops/mutate" \
  --header "Authorization: Bearer $CABANE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary '{
    "op": "files.write",
    "args": {
      "path": "/api-example/hello.md",
      "content": "# Hello\n\nCreated from the Cabane API.\n"
    }
  }'

On the first run, the response is:

{
  "ok": true,
  "result": {
    "path": "/api-example/hello.md",
    "mime": "text/markdown",
    "size": 38,
    "sha256": "edb3a4c9af5d8b0e6e755719bae5ffeee15c6aaca2bb994ec08f678dc116f52e",
    "created": true
  }
}

ok: true means the operation succeeded. created: true means it created a new file; the parent folder is created automatically if needed. sha256 identifies the stored content.

Always inspect ok. An operation can fail inside an HTTP 200 response, which curl's --fail-with-body does not treat as an error.

If you repeat this request, the existing path produces ok: false with error.kind: "conflict" and error.code: "name_conflict". Continue to the read below to verify the file from your first run. If the path already contained someone else's content, change hello.md to an unused filename in both the write and read requests. For a deliberate update, follow Safe writes and retries.

4Read the file

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  "$CABANE_BASE/api/workspaces/$CABANE_WORKSPACE_ID/ops/query" \
  --header "Authorization: Bearer $CABANE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary '{
    "op": "files.read",
    "args": {
      "path": "/api-example/hello.md"
    }
  }'

Check for ok: true. The result.content value should be "# Hello\n\nCreated from the Cabane API.\n", and result.sha256 should match the write response. result.more: null means the whole requested text was returned.

You have now written and read workspace content. Use the Operation reference to choose your next action, or follow Conversations and agents to send a request to an agent.

When you finish this terminal session, clear the token variable:

unset CABANE_TOKEN