API Reference

← Back to YouLab

Complete HTTP API reference for the YouLab service.

Base URL

http://localhost:8100

Authentication

Currently no authentication required. Optional API key support via YOULAB_SERVICE_API_KEY.

---

Health

GET /health

Check service health and Letta connection.

Response:

{
  "status": "ok",
  "letta_connected": true,
  "honcho_connected": true,
  "version": "0.1.0"
}

Field	Type	Description
status	string	"ok" or "degraded"
letta_connected	boolean	Letta server reachable
honcho_connected	boolean	Honcho service reachable
version	string	Service version (e.g., "0.1.0")

---

Agents

POST /agents

Create a new agent for a user.

Request:

{
  "user_id": "user123",
  "agent_type": "tutor",
  "user_name": "Alice"
}

Field	Type	Required	Default
user_id	string	Yes	-
agent_type	string	No	"tutor"
user_name	string	No	null

Response (201):

{
  "agent_id": "agent-abc123",
  "user_id": "user123",
  "agent_type": "tutor",
  "agent_name": "youlab_user123_tutor",
  "created_at": "2025-12-31T10:00:00Z"
}

Errors:

• 400 - Unknown agent type
• 500 - Agent created but info retrieval failed
• 503 - Letta unavailable

---

GET /agents/{agent_id}

Get agent by ID.

Response:

{
  "agent_id": "agent-abc123",
  "user_id": "user123",
  "agent_type": "tutor",
  "agent_name": "youlab_user123_tutor",
  "created_at": "2025-12-31T10:00:00Z"
}

Errors:

• 404 - Agent not found

---

GET /agents

List agents.

Query Parameters:

Parameter	Type	Description
user_id	string	Filter by user

Response:

{
  "agents": [
    {
      "agent_id": "agent-abc123",
      "user_id": "user123",
      "agent_type": "tutor",
      "agent_name": "youlab_user123_tutor",
      "created_at": "2025-12-31T10:00:00Z"
    }
  ]
}

---

Chat

POST /chat

Send message (synchronous).

Request:

{
  "agent_id": "agent-abc123",
  "message": "Help me brainstorm essay topics",
  "chat_id": "chat-xyz",
  "chat_title": "Essay Brainstorming"
}

Field	Type	Required
agent_id	string	Yes
message	string	Yes
chat_id	string	No
chat_title	string	No

Response:

{
  "response": "Great! Let's explore some essay topics...",
  "agent_id": "agent-abc123"
}

Errors:

• 404 - Agent not found
• 503 - Communication failed

---

POST /chat/stream

Send message with SSE streaming.

Request:

{
  "agent_id": "agent-abc123",
  "message": "What makes a compelling narrative?",
  "chat_id": "chat-xyz",
  "chat_title": "Essay Writing",
  "enable_thinking": true
}

Field	Type	Required	Default
agent_id	string	Yes	-
message	string	Yes	-
chat_id	string	No	null
chat_title	string	No	null
enable_thinking	boolean	No	true

Response (SSE):

data: {"type": "status", "content": "Thinking..."}

data: {"type": "message", "content": "A compelling narrative..."}

data: {"type": "done"}

Event Types:

Type	Description
status	Processing indicator
message	Response content
done	Stream complete
error	Error message

---

Strategy

POST /strategy/documents

Upload document to archival memory.

Request:

{
  "content": "# Architecture\n\nYouLab uses...",
  "tags": ["architecture", "design"]
}

Field	Type	Required	Default
content	string	Yes	-
tags	array[string]	No	[]

Response (201):

{
  "success": true
}

Errors:

• 503 - Letta unavailable

---

POST /strategy/ask

Query strategy agent.

Request:

{
  "question": "What is the YouLab architecture?"
}

Response:

{
  "response": "Based on the documentation..."
}

Errors:

• 503 - Letta unavailable

---

GET /strategy/documents

Search archival memory.

Query Parameters:

Parameter	Type	Default
query	string	Required
limit	integer	5

Response:

{
  "documents": [
    "[TAGS: architecture]\n# Architecture\n..."
  ]
}

Errors:

• 503 - Letta unavailable

---

GET /strategy/health

Check strategy agent status.

Response:

{
  "status": "ready",
  "agent_exists": true
}

Status	Meaning
ready	Agent exists
not_ready	Agent not created

---

Background

GET /background/agents

List configured background agents.

Response:

[
  {
    "id": "insight-harvester",
    "name": "Student Insight Harvester",
    "course_id": "college-essay",
    "enabled": true,
    "triggers": {
      "schedule": "0 3 * * *",
      "idle_enabled": false,
      "manual": true
    },
    "query_count": 3
  }
]

---

POST /background/{agent_id}/run

Manually trigger a background agent.

Request (optional):

{
  "user_ids": ["user123"]
}

Field	Type	Required
user_ids	array	No

Response:

{
  "agent_id": "insight-harvester",
  "started_at": "2025-01-08T03:00:00Z",
  "completed_at": "2025-01-08T03:05:00Z",
  "users_processed": 25,
  "queries_executed": 75,
  "enrichments_applied": 68,
  "error_count": 7,
  "errors": []
}

Errors:

• 404 - Agent not found
• 500 - System not initialized

---

POST /background/config/reload

Reload TOML configuration.

Query Parameters:

Parameter	Type	Default
config_dir	string	config/courses

Response:

{
  "success": true,
  "courses_loaded": 1,
  "course_ids": ["college-essay"],
  "message": "Configuration reloaded successfully"
}

---

Error Responses

All errors follow this format:

{
  "detail": "Error message here"
}

Code	Meaning
400	Bad request (invalid input)
404	Resource not found
500	Internal server error
503	Service unavailable (Letta down)

---

cURL Examples

Create Agent

curl -X POST http://localhost:8100/agents \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user123", "agent_type": "tutor"}'

Send Message

curl -X POST http://localhost:8100/chat \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "...", "message": "Hello"}'

Stream Response

curl -N -X POST http://localhost:8100/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "...", "message": "Hello"}'

Upload Document

curl -X POST http://localhost:8100/strategy/documents \
  -H "Content-Type: application/json" \
  -d '{"content": "# Docs", "tags": ["docs"]}'

---

Related Pages

• HTTP Service - Implementation details
• Schemas - Request/response models
• Background Agents - Background agent system
• Quickstart - Getting started