Skip to main content

​
Overview

The Tensors API provides endpoints for creating, reading, updating, and deleting cognitive tensors. Tensors are 20-dimensional structures containing context (8), biology (4), and behavior (8) dimensions.

​
Tensor Structure

Each tensor contains:
  • tensor_id: Unique identifier
  • entity_id: Entity this tensor represents
  • world_id: World/simulation context (optional)
  • values: 20-dimensional tensor values (context, biology, behavior)
  • maturity: Training maturity score (0.0-1.0)
  • training_cycles: Number of training iterations
  • description: Natural language description for semantic search
  • category: Category path (e.g., “profession/detective”)
  • access_level: Permission level (private/shared/public)
  • owner_id: User who owns this tensor

​
List Tensors

Get a paginated list of tensors you have access to.
GET /tensors
curl -X GET "http://localhost:8080/tensors?page=1&page_size=50" \
  -H "X-API-Key: tp_your_api_key_here"

​
Query Parameters

​
page
integer
default:"1"
Page number (1-indexed)
​
page_size
integer
default:"50"
Number of tensors per page (1-100)
​
entity_id
string
Filter by entity ID
​
world_id
string
Filter by world ID

​
Response

​
tensors
array
Array of tensor objects
​
total
integer
Total number of accessible tensors
​
page
integer
Current page number
​
page_size
integer
Page size used
{
  "tensors": [
    {
      "tensor_id": "tensor-abc123",
      "entity_id": "entity-001",
      "world_id": "world-sim-01",
      "values": {
        "context": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
        "biology": [0.1, 0.2, 0.3, 0.4],
        "behavior": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
      },
      "maturity": 0.95,
      "training_cycles": 100,
      "version": 5,
      "description": "Detective persona with analytical thinking",
      "category": "profession/detective",
      "access_level": "private",
      "owner_id": "user-123",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-06T12:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

​
Create Tensor

Create a new tensor. The current user becomes the owner.
POST /tensors
curl -X POST http://localhost:8080/tensors \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "entity-001",
    "world_id": "world-sim-01",
    "values": {
      "context": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
      "biology": [0.1, 0.2, 0.3, 0.4],
      "behavior": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
    },
    "description": "Detective persona with analytical thinking",
    "category": "profession/detective",
    "maturity": 0.95,
    "training_cycles": 100,
    "access_level": "private"
  }'

​
Request Body

​
tensor_id
string
Optional tensor ID (generated if not provided)
​
entity_id
string
required
Entity this tensor belongs to
​
world_id
string
World/simulation context
​
values
object
required
Tensor dimension values
​
values.context
array
required
Context dimensions (8 values, 0.0-1.0)
​
values.biology
array
required
Biology dimensions (4 values, 0.0-1.0)
​
values.behavior
array
required
Behavior dimensions (8 values, 0.0-1.0)
​
description
string
Natural language description for RAG
​
category
string
Category path (e.g., “profession/detective”)
​
maturity
number
default:"0.0"
Maturity score (0.0-1.0)
​
training_cycles
integer
default:"0"
Number of training cycles
​
access_level
string
default:"private"
Access level: private, shared, or public

​
Response

Status: 201 Created Returns the created tensor object.

​
Get Tensor

Get a single tensor by ID.
GET /tensors/{tensor_id}
curl -X GET http://localhost:8080/tensors/tensor-abc123 \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

Returns a tensor object (same structure as create response).

​
Errors

  • 404 Not Found - Tensor doesn’t exist
  • 403 Forbidden - No read access to tensor

​
Update Tensor

Update an existing tensor. Requires write permission (owner only).
PUT /tensors/{tensor_id}
curl -X PUT http://localhost:8080/tensors/tensor-abc123 \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "maturity": 0.98,
    "training_cycles": 150,
    "description": "Updated description"
  }'

​
Request Body

All fields are optional. Only provided fields are updated.
​
entity_id
string
Updated entity ID
​
world_id
string
Updated world ID
​
values
object
Updated tensor values
​
description
string
Updated description
​
category
string
Updated category
​
maturity
number
Updated maturity (0.0-1.0)
​
training_cycles
integer
Updated training cycles
​
access_level
string
Updated access level

​
Response

Returns the updated tensor object.

​
Errors

  • 404 Not Found - Tensor doesn’t exist
  • 403 Forbidden - No write access (not owner)

​
Delete Tensor

Delete a tensor. Requires delete permission (owner only).
DELETE /tensors/{tensor_id}
curl -X DELETE http://localhost:8080/tensors/tensor-abc123 \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

Status: 204 No Content

​
Errors

  • 404 Not Found - Tensor doesn’t exist
  • 403 Forbidden - No delete access (not owner)

​
Share Tensor

Share a tensor with another user.
POST /tensors/{tensor_id}/share
curl -X POST http://localhost:8080/tensors/tensor-abc123/share \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-456"}'

​
Request Body

​
user_id
string
required
User ID to share with

​
Response

{
  "message": "Tensor shared with user-456"
}

​
Revoke Sharing

Revoke sharing from a user.
DELETE /tensors/{tensor_id}/share/{target_user_id}
curl -X DELETE http://localhost:8080/tensors/tensor-abc123/share/user-456 \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

{
  "message": "Sharing revoked from user-456"
}

​
Set Access Level

Change tensor access level.
PUT /tensors/{tensor_id}/access
curl -X PUT http://localhost:8080/tensors/tensor-abc123/access \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"access_level": "public"}'

​
Request Body

​
access_level
string
required
New access level: private, shared, or public

​
Response

{
  "message": "Access level set to public"
}

​
Fork Tensor

Create a copy of a tensor that you own.
POST /tensors/{tensor_id}/fork
curl -X POST "http://localhost:8080/tensors/tensor-abc123/fork?new_id=tensor-fork-001" \
  -H "X-API-Key: tp_your_api_key_here"

​
Query Parameters

​
new_id
string
ID for the forked tensor (generated if not provided)

​
Response

Status: 201 Created Returns the forked tensor object with updated description.

​
Get Statistics

Get database statistics.
GET /tensors/stats/summary
curl -X GET http://localhost:8080/tensors/stats/summary \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

​
total_tensors
integer
Total tensor count
​
operational_count
integer
Tensors with maturity >= 0.95
​
training_count
integer
Tensors with maturity < 0.95
​
avg_maturity
number
Average maturity score
​
total_versions
integer
Total version entries
{
  "total_tensors": 42,
  "operational_count": 38,
  "training_count": 4,
  "avg_maturity": 0.87,
  "total_versions": 156
}

Build docs developers (and LLMs) love

Get started for freeTalk to us