API Endpoints

Complete reference for all GatheRing REST API endpoints.

Base URL: http://localhost:8000

Health & Status

GET /health

Check API health status with system overview.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 3600.5,
  "agents_count": 5,
  "circles_count": 2,
  "active_tasks": 3
}

GET /health/system

Get real-time system metrics (CPU, memory, disk, load average).

Response:

{
  "cpu": {
    "percent": 25.5,
    "count": 8,
    "frequency_mhz": 3200.0
  },
  "memory": {
    "total_gb": 32.0,
    "available_gb": 18.5,
    "used_gb": 13.5,
    "percent": 42.2
  },
  "disk": {
    "total_gb": 500.0,
    "used_gb": 250.0,
    "free_gb": 250.0,
    "percent": 50.0
  },
  "load_average": {
    "1min": 1.5,
    "5min": 1.2,
    "15min": 0.9
  },
  "uptime_seconds": 3600.5
}

GET /health/checks

Get detailed health checks for all services.

Response:

{
  "checks": [
    {
      "name": "API Server",
      "status": "healthy",
      "message": "Responding normally",
      "last_check": "2025-01-01T12:00:00Z"
    },
    {
      "name": "Database",
      "status": "healthy",
      "message": "PostgreSQL connected",
      "last_check": "2025-01-01T12:00:00Z"
    },
    {
      "name": "Memory Usage",
      "status": "healthy",
      "value": "42.2%",
      "message": "Normal",
      "last_check": "2025-01-01T12:00:00Z"
    },
    {
      "name": "Disk Space",
      "status": "healthy",
      "value": "50.0%",
      "message": "Sufficient space",
      "last_check": "2025-01-01T12:00:00Z"
    },
    {
      "name": "Agents",
      "status": "healthy",
      "value": "5",
      "message": "5 agent(s) registered",
      "last_check": "2025-01-01T12:00:00Z"
    },
    {
      "name": "Circles",
      "status": "healthy",
      "value": "1/2",
      "message": "1 running, 2 total",
      "last_check": "2025-01-01T12:00:00Z"
    }
  ],
  "overall_status": "healthy"
}

Status Values:

healthy: Service operating normally
warning: Service degraded (memory >70%, disk >80%)
critical: Service critical (memory >90%, disk >90%, connection failed)

GET /health/ready

Kubernetes readiness probe. Returns 503 during graceful shutdown to allow load balancers to drain connections.

Response (healthy):

{
  "ready": true
}

Response (shutting down): 503 Service Unavailable

{
  "ready": false,
  "reason": "shutting_down"
}

GET /health/live

Kubernetes liveness probe.

Response:

{
  "alive": true
}

Agents

GET /agents

List all agents.

Query Parameters:

Parameter	Type	Default	Description
`status`	string	-	Filter by status
`limit`	int	50	Max results
`offset`	int	0	Pagination offset

Response:

[
  {
    "id": 1,
    "name": "Sophie",
    "role": "Architect",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "status": "idle",
    "created_at": "2025-01-01T00:00:00Z"
  }
]

POST /agents

Create a new agent.

Request Body:

{
  "name": "Sophie",
  "role": "Lead Architect",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "personality": {
    "traits": ["analytical", "creative"],
    "communication_style": "professional"
  },
  "config": {
    "temperature": 0.7
  }
}

Response: 201 Created

{
  "id": 1,
  "name": "Sophie",
  "role": "Lead Architect",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "status": "idle",
  "created_at": "2025-01-01T00:00:00Z"
}

GET /agents/{id}

Get agent by ID.

Response:

{
  "id": 1,
  "name": "Sophie",
  "role": "Lead Architect",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "personality": {...},
  "config": {...},
  "status": "idle",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

PATCH /agents/{id}

Update an agent.

Request Body:

{
  "role": "Senior Architect",
  "config": {
    "temperature": 0.8
  }
}

DELETE /agents/{id}

Delete an agent.

Response: 204 No Content

GET /agents/{id}/sessions

Get agent sessions.

POST /agents/{id}/sessions

Start a new session.

GET /agents/{id}/memories

Get agent memories.

Circles

GET /circles

List all circles.

Response:

[
  {
    "id": 1,
    "name": "dev-team",
    "display_name": "Development Team",
    "status": "active",
    "agent_count": 3
  }
]

POST /circles

Create a new circle.

Request Body:

{
  "name": "dev-team",
  "display_name": "Development Team",
  "description": "Frontend and backend developers",
  "config": {
    "max_agents": 10,
    "conversation_mode": "round_robin"
  }
}

GET /circles/{name}

Get circle by name.

PATCH /circles/{name}

Update a circle.

DELETE /circles/{name}

Delete a circle.

POST /circles/{name}/start

Start a circle.

POST /circles/{name}/pause

Pause a circle.

POST /circles/{name}/resume

Resume a paused circle.

POST /circles/{name}/archive

Archive a circle.

GET /circles/{name}/agents

List agents in a circle.

POST /circles/{name}/agents

Add agent to circle.

Request Body:

{
  "agent_id": 1,
  "role": "member"
}

DELETE /circles/{name}/agents/{agent_id}

Remove agent from circle.

Conversations

GET /conversations

List conversations.

Query Parameters:

Parameter	Type	Description
`circle_name`	string	Filter by circle
`status`	string	Filter by status
`limit`	int	Max results

POST /conversations

Create a new conversation.

Request Body:

{
  "circle_name": "dev-team",
  "topic": "API Design Review",
  "agent_ids": [1, 2, 3],
  "initial_prompt": "Let's review the new API design",
  "max_turns": 20
}

GET /conversations/{id}

Get conversation details.

GET /conversations/{id}/messages

Get conversation messages.

POST /conversations/{id}/advance

Advance the conversation.

Request Body:

{
  "prompt": "What about error handling?"
}

POST /conversations/{id}/end

End the conversation.

Workspace

GET /workspace/{id}/info

Get workspace information.

Response:

{
  "id": 1,
  "path": "/home/user/project",
  "name": "my-project",
  "git_enabled": true,
  "current_branch": "main"
}

GET /workspace/{id}/files

List files in workspace.

Query Parameters:

Parameter	Type	Description
`path`	string	Directory path
`recursive`	bool	Include subdirectories

GET /workspace/{id}/files/{path}

Read file content.

Response:

{
  "path": "src/main.py",
  "content": "print('hello')",
  "language": "python",
  "size": 15
}

PUT /workspace/{id}/files/{path}

Write file content.

Request Body:

{
  "content": "print('updated')"
}

DELETE /workspace/{id}/files/{path}

Delete a file.

POST /workspace/{id}/files/{path}/rename

Rename a file.

Request Body:

{
  "new_path": "src/app.py"
}

GET /workspace/{id}/git/status

Get git status.

Response:

{
  "branch": "main",
  "ahead": 2,
  "behind": 0,
  "staged": ["src/main.py"],
  "modified": ["README.md"],
  "untracked": ["new_file.py"]
}

GET /workspace/{id}/git/commits

Get commit history.

Query Parameters:

Parameter	Type	Default
`limit`	int	20
`branch`	string	current

POST /workspace/{id}/git/stage

Stage files.

Request Body:

{
  "files": ["src/main.py", "README.md"]
}

POST /workspace/{id}/git/unstage

Unstage files.

POST /workspace/{id}/git/commit

Create a commit.

Request Body:

{
  "message": "Add new feature"
}

POST /workspace/{id}/git/push

Push to remote.

POST /workspace/{id}/git/pull

Pull from remote.

GET /workspace/{id}/git/diff

Get file diff.

Query Parameters:

Parameter	Type	Description
`file`	string	File path
`staged`	bool	Staged diff

Memory

GET /memory/search

Semantic memory search.

Query Parameters:

Parameter	Type	Description
`query`	string	Search query
`agent_id`	int	Filter by agent
`scope`	string	Memory scope
`limit`	int	Max results

Response:

[
  {
    "id": 1,
    "key": "user_name",
    "value": "Alice",
    "similarity": 0.92,
    "scope": "agent"
  }
]

POST /memory

Create a memory.

Request Body:

{
  "agent_id": 1,
  "scope": "agent",
  "key": "preference",
  "value": "Likes detailed explanations",
  "memory_type": "fact"
}

DELETE /memory/{id}

Delete a memory.

Dashboard

GET /dashboard/circles

Get dashboard circle summary.

GET /dashboard/agents

Get dashboard agent summary.

GET /dashboard/activity

Get recent activity feed.

GET /dashboard/stats

Get system statistics.

Settings

GET /settings

Get all application settings including LLM providers, database, and application configuration.

Response:

{
  "providers": {
    "anthropic": {
      "api_key": "sk-a...xyz",
      "default_model": "claude-sonnet-4-5",
      "is_configured": true,
      "models": [
        {
          "id": 1,
          "model_name": "claude-sonnet-4-20250514",
          "model_alias": "claude-4-sonnet",
          "vision": true,
          "extended_thinking": false
        }
      ]
    },
    "openai": {
      "api_key": null,
      "default_model": "gpt-4",
      "is_configured": false,
      "models": []
    },
    "ollama": {
      "base_url": "http://localhost:11434",
      "default_model": "llama3.2",
      "is_configured": true,
      "models": []
    }
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "gathering",
    "user": "gathering",
    "is_connected": true
  },
  "application": {
    "environment": "development",
    "debug": true,
    "log_level": "INFO"
  }
}

Supported Providers:

anthropic: Anthropic Claude models
openai: OpenAI GPT models
deepseek: DeepSeek models
mistral: Mistral AI models
google: Google Gemini models
ollama: Local Ollama models

PATCH /settings/providers/{provider}

Update a provider’s settings.

Path Parameters:

Parameter	Type	Description
`provider`	string	Provider name (anthropic, openai, etc.)

Request Body:

{
  "api_key": "sk-new-key...",
  "default_model": "claude-sonnet-4-5",
  "base_url": "http://localhost:11434"
}

Response:

{
  "api_key": "sk-n...key",
  "default_model": "claude-sonnet-4-5",
  "is_configured": true,
  "models": []
}

PATCH /settings/application

Update application settings.

Request Body:

{
  "debug": false,
  "log_level": "WARNING"
}

Valid log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

Response:

{
  "environment": "development",
  "debug": false,
  "log_level": "WARNING"
}

POST /settings/providers/{provider}/test

Test connection to a provider.

Response (success):

{
  "success": true,
  "message": "Anthropic API key is valid"
}

Response (failure):

{
  "success": false,
  "message": "Invalid API key"
}

Ollama response:

{
  "success": true,
  "message": "Connected to Ollama. 5 models available.",
  "models": ["llama3.2", "codellama", "mistral"]
}

Tools (Agent Capabilities)

Manage which skills/tools are enabled for each agent.

GET /tools/skills

List all available skills.

Query Parameters:

Parameter	Type	Description
`category`	string	Filter by category

Response:

[
  {
    "id": 1,
    "name": "git",
    "display_name": "Git",
    "description": "Repository management, commits, branches, PRs",
    "category": "core",
    "required_permissions": ["git", "read", "write"],
    "is_dangerous": false,
    "is_enabled": true,
    "version": "1.0.0",
    "tools_count": 5
  }
]

Skill Categories:

core: Git, Test, Filesystem
code: Code Execution, Analysis
system: Shell, Database, Deploy
web: Web Search, Scraper, HTTP
ai: AI/ML operations
communication: Email, Notifications, Social
productivity: Calendar, Docs
media: Image, PDF
cloud: Cloud providers, Monitoring
gathering: Goals, Pipelines, Tasks, Schedules

GET /tools/skills/categories

Get skill categories with counts.

Response:

{
  "core": 5,
  "code": 2,
  "system": 3,
  "web": 3,
  "gathering": 6
}

GET /tools/agents/{agent_id}

Get all tools for an agent with enabled/disabled status.

Response:

{
  "agent_id": 1,
  "agent_name": "Sophie",
  "tools": [
    {
      "skill_id": 1,
      "skill_name": "git",
      "skill_display_name": "Git",
      "skill_category": "core",
      "required_permissions": ["git", "read", "write"],
      "is_dangerous": false,
      "is_enabled": true,
      "usage_count": 42,
      "last_used_at": "2025-01-01T12:00:00Z"
    }
  ],
  "enabled_count": 12,
  "total_count": 24
}

PATCH /tools/agents/{agent_id}/skills/{skill_name}

Enable or disable a tool for an agent.

Request Body:

{
  "is_enabled": true
}

Response:

{
  "agent_id": 1,
  "skill_name": "git",
  "is_enabled": true,
  "message": "Tool 'git' enabled for agent 1"
}

POST /tools/agents/{agent_id}/skills/bulk

Bulk enable/disable multiple tools.

Request Body:

{
  "skill_names": ["git", "test", "shell"],
  "is_enabled": true
}

Response:

{
  "agent_id": 1,
  "updated_count": 3,
  "is_enabled": true,
  "message": "3 tools enabled"
}

POST /tools/agents/{agent_id}/skills/enable-all

Enable all tools for an agent.

Query Parameters:

Parameter	Type	Description
`category`	string	Only enable tools in this category

Response:

{
  "agent_id": 1,
  "enabled_count": 24,
  "category": null,
  "message": "Enabled 24 tools"
}

POST /tools/agents/{agent_id}/skills/disable-all

Disable all tools for an agent.

Query Parameters:

Parameter	Type	Description
`category`	string	Only disable tools in this category

GET /tools/agents/{agent_id}/enabled

Get list of enabled skill names for an agent.

Response:

{
  "agent_id": 1,
  "enabled_skills": ["git", "test", "filesystem", "code"]
}

Rate Limiting

All endpoints enforce per-endpoint rate limits via slowapi. Rate limit tiers:

Tier	Limit	Endpoints
`strict`	10/minute	`/auth/login`, `/auth/register`
`standard`	60/minute	Most CRUD endpoints
`relaxed`	200/minute	Read-heavy endpoints (`GET /agents`, `GET /circles`)
`bulk`	30/minute	Bulk operations, imports

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707616800

Error Responses

All endpoints may return:

400 Bad Request

{
  "detail": "Invalid request body"
}

404 Not Found

{
  "detail": "Resource not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error

{
  "detail": "Internal server error"
}