API Documentation

Full reference for Treenode API.

Introduction

Treenode API lets you manage roles, run inference, and operate knowledge files programmatically. Send all requests over HTTPS to `https://api.treenode.online`.

Authentication

Two auth modes are supported: 1. **API Token** (recommended for production) Add header: `X-API-Token: tk_live_xxxxx` 2. **Bearer Token** (for console debugging) Add header: `Authorization: Bearer eyJhbGciOi...`

Quick Example

curl -X POST https://api.treenode.online/v1/open/infer \ -H "X-API-Token: tk_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Hi, please introduce yourself", "output_mode": "auto" }'

POST /v1/roles

POST/v1/roles

Create a new role.

Request example

{
  "name": "Support Assistant",
  "background": "You are a professional support assistant...",
  "avatar_url": "https://example.com/avatar.png",
  "traits": ["friendly", "professional", "patient"]
}

Response example

{
  "id": "role_abc123",
  "name": "Support Assistant",
  "version": 1,
  "status": "draft",
  "created_at": "2026-01-01T00:00:00Z"
}

GET /v1/roles

GET/v1/roles

List roles.

Parameters

Name	Type	Description
`page`	number	Page index, default 1
`page_size`	number	Page size, default 20
`status`	string	Filter: draft / active / archived

Response example

{
  "items": [...],
  "total": 42,
  "page": 1,
  "page_size": 20
}

POST /v1/roles/{id}/freeze

POST/v1/roles/{id}/freeze

Freeze a role into a callable version and issue an API token.

Response example

{
  "id": "role_abc123",
  "version": 2,
  "status": "active",
  "api_token": "tk_live_xxxxx"
}

POST /v1/open/infer

POST/v1/open/infer

Run inference with a role.

Request example

{
  "prompt": "Hi, please introduce yourself",
  "output_mode": "auto",
  "stream": false
}

Response example

{
  "request_id": "req_xxx",
  "type": "text",
  "content": "Hi! I am...",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50
  }
}

Streaming

Set `stream: true` to enable SSE output. ``` data: {"type": "delta", "content": "H"} data: {"type": "delta", "content": "i"} data: {"type": "done", "usage": {...}} ```

POST /v1/roles/{id}/knowledge/files

POST/v1/roles/{id}/knowledge/files

Upload knowledge files (including resumable uploads).

Response example

{
  "file_id": "file_xxx",
  "filename": "manual.pdf",
  "status": "queued",
  "created_at": "2026-01-01T00:00:00Z"
}