Gnosari Documentation

Appearance

Teams ​

Manage multi-agent teams and collaboration workflows.

Teams group multiple agents together for coordinated task execution. Teams support the same access control levels as agents (PUBLIC, PASSWORD_PROTECTED, PRIVATE) and can be configured via JSON using push/pull operations.

GET /teams ​

List all teams for the authenticated account.

Authentication: Required (JWT or API Key)

Query Parameters:

  • skip (integer): Pagination offset (default: 0)
  • limit (integer): Results per page (default: 50, max: 200)
  • sort_by (string): Sort field (updated_at | created_at | name, default: updated_at)
  • sort_order (string): Sort direction (asc | desc, default: desc)

Response:

json
{
  "data": [
    {
      "id": 10,
      "name": "Support Team",
      "identifier": "support-team",
      "description": "Customer support team with multiple agents",
      "access_level": "PRIVATE",
      "image_url": null,
      "configuration": {},
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T14:30:00Z",
      "agents": [
        {
          "id": 1,
          "name": "Support Agent",
          "identifier": "support-agent",
          "description": "Handles customer inquiries",
          "instructions": "You are a helpful support agent...",
          "model": "gpt-4o",
          "temperature": 0.7,
          "access_level": "PRIVATE",
          "knowledge_sources": [],
          "tools": [],
          "traits": []
        }
      ]
    }
  ],
  "pagination": { "total": 12, "skip": 0, "limit": 50, "has_more": false }
}

Example:

bash
curl -X GET "https://api.gnosari.com/api/v1/teams" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /teams ​

Create a new team.

Authentication: Required (JWT or API Key)

Request Body:

json
{
  "name": "Sales Team",
  "description": "Multi-agent sales team",
  "identifier": "sales-team",
  "access_level": "PRIVATE",
  "image_url": null,
  "configuration": {},
  "agent_ids": [1, 2, 3]
}

Field Details:

  • name (string, required): Team display name
  • description (string, optional): Team description
  • identifier (string, optional): URL-friendly identifier (auto-generated from name if not provided)
  • access_level (string, default: PRIVATE): Access control (PRIVATE | PASSWORD_PROTECTED | PUBLIC)
  • access_password (string, optional): Required if access_level is PASSWORD_PROTECTED (min 8 characters)
  • image_url (string, optional): Team avatar image URL
  • configuration (object, optional): Additional configuration
  • agent_ids (array[int], default: []): Agent IDs to include in team

Status: 201 Created

Response: Full team object

Errors:

  • 400: Invalid input (missing required fields, invalid password)
  • 401: Authentication required
  • 403: Insufficient permissions

Example:

bash
curl -X POST "https://api.gnosari.com/api/v1/teams" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Team",
    "description": "Multi-agent sales team",
    "agent_ids": [1, 2, 3]
  }'

GET /teams/{team_id_or_identifier} ​

Get a single team by ID or identifier.

Authentication: Depends on team's access_level:

  • PUBLIC: No authentication required
  • PASSWORD_PROTECTED: Requires X-Access-Password header
  • PRIVATE: Requires JWT or API Key

Path Parameters:

  • team_id_or_identifier (int|string): Numeric ID (e.g., 10) or string identifier (e.g., "sales-team")

Headers (for PASSWORD_PROTECTED teams):

  • X-Access-Password: Team access password

Response: Single team object

Errors:

  • 401: Authentication required (for PRIVATE teams)
  • 403: Invalid password (for PASSWORD_PROTECTED teams) or insufficient permissions
  • 404: Team not found

Example:

bash
# By ID
curl -X GET "https://api.gnosari.com/api/v1/teams/10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# By identifier
curl -X GET "https://api.gnosari.com/api/v1/teams/sales-team" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Password-protected team
curl -X GET "https://api.gnosari.com/api/v1/teams/public-team" \
  -H "X-Access-Password: mypassword"

PUT /teams/{team_id_or_identifier} ​

Update an existing team.

Authentication: Required (JWT or API Key)

Path Parameters:

  • team_id_or_identifier (int|string): Numeric ID or string identifier

Request Body: All fields optional (provide only fields to update)

json
{
  "name": "Updated Sales Team",
  "description": "Updated description",
  "agent_ids": [1, 2, 3, 4]
}

Field Details: Same as POST /teams, but all fields are optional

Response: Updated team object (full)

Errors:

  • 400: Invalid input
  • 401: Authentication required
  • 403: Insufficient permissions (team belongs to different account)
  • 404: Team not found

Example:

bash
curl -X PUT "https://api.gnosari.com/api/v1/teams/sales-team" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": [1, 2, 3, 4]}'

DELETE /teams/{team_id_or_identifier} ​

Delete a team.

Authentication: Required (JWT or API Key)

Path Parameters:

  • team_id_or_identifier (int|string): Numeric ID or string identifier

Response: No response body (204 No Content)

Errors:

  • 401: Authentication required
  • 403: Insufficient permissions
  • 404: Team not found

Example:

bash
curl -X DELETE "https://api.gnosari.com/api/v1/teams/10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /teams/push ​

Create a team from comprehensive JSON configuration.

Push operations allow you to define complete team configurations including agents, tools, knowledge sources, traits, event listeners, and delegations in a single JSON payload. This is ideal for version-controlled team definitions and infrastructure-as-code workflows.

Authentication: Required (JWT or API Key, NOT master API key)

Request Body:

json
{
  "name": "AI Development Team",
  "description": "Multi-agent team for software development tasks",
  "agents": [
    {
      "name": "code_reviewer",
      "description": "Reviews code for quality and best practices",
      "system_prompt": "You are an expert code reviewer.",
      "model": "claude-3-5-sonnet-20241022",
      "temperature": 0.1,
      "max_tokens": 4000,
      "image_url": "https://cdn.example.com/avatar-reviewer.png",
      "publication": {
        "access_level": "public",
        "chat_uri": "code-review-bot",
        "domain": "example.com"
      },
      "configuration": {
        "chat_ui": {
          "empty_title": "Code Review Assistant",
          "empty_description": "Upload your code and I'll review it for quality and best practices.",
          "greeting": "Hello! I'm here to help you improve your code.",
          "suggested_prompts": [
            {
              "icon": "i-heroicons-code-bracket",
              "title": "Review my code",
              "text": "Can you review this code for best practices?"
            },
            {
              "icon": "i-heroicons-shield-check",
              "title": "Security check",
              "text": "Are there any security vulnerabilities in this code?"
            }
          ]
        }
      },
      "events": [
        {
          "type": "code_push",
          "description": "Trigger on code repository pushes",
          "enabled": true,
          "config": {
            "repositories": ["main", "dev"],
            "file_patterns": ["*.py", "*.js", "*.ts"]
          }
        }
      ],
      "traits": ["analytical", "detail_oriented", "security_focused"],
      "delegations": [
        {
          "to_agent": "security_analyzer",
          "condition": "security_issue_detected",
          "description": "Delegate security issues to security specialist"
        }
      ]
    },
    {
      "name": "security_analyzer",
      "description": "Specialized in security analysis",
      "system_prompt": "You are a security expert.",
      "model": "claude-3-5-sonnet-20241022",
      "temperature": 0.0,
      "max_tokens": 3000,
      "traits": ["security_focused", "thorough", "risk_aware"]
    }
  ],
  "tools": [
    {
      "name": "github_integration",
      "description": "GitHub API integration for repository operations",
      "type": "mcp",
      "config": {
        "server_name": "github-mcp",
        "server_path": "/opt/mcp-servers/github",
        "server_args": ["--token", "${GITHUB_TOKEN}"],
        "capabilities": ["read_repos", "create_issues", "comment_pr"]
      }
    },
    {
      "name": "code_analysis",
      "description": "Static code analysis tool",
      "type": "external",
      "config": {
        "command": "pylint",
        "args": ["--output-format=json"],
        "timeout": 30
      }
    }
  ],
  "knowledge": [
    {
      "name": "coding_standards",
      "description": "Company coding standards and best practices",
      "type": "document",
      "source": "https://company.com/docs/coding-standards.md",
      "processing": {
        "chunk_size": 1000,
        "overlap": 200,
        "embedding_model": "text-embedding-3-small"
      }
    },
    {
      "name": "security_guidelines",
      "description": "Security guidelines and vulnerability patterns",
      "type": "document_collection",
      "source": "/security/guidelines/",
      "processing": {
        "recursive": true,
        "file_patterns": ["*.md", "*.txt"],
        "chunk_size": 1500,
        "overlap": 300
      }
    }
  ],
  "traits": [
    {
      "name": "analytical",
      "category": "cognitive",
      "description": "Strong analytical and logical reasoning abilities",
      "tags": ["reasoning", "problem_solving"]
    },
    {
      "name": "security_focused",
      "category": "specialty",
      "description": "Specialized knowledge in security practices",
      "tags": ["security", "vulnerability", "compliance"]
    }
  ],
  "overrides": {
    "global": {
      "max_tokens": 4000,
      "temperature": 0.2
    },
    "agent_specific": {
      "security_analyzer": {
        "temperature": 0.0,
        "system_prompt_suffix": " Always prioritize security over convenience."
      }
    }
  },
  "filters": {
    "include_components": ["agents", "tools", "knowledge"],
    "exclude_components": [],
    "agent_filters": {
      "include_traits": ["security_focused", "analytical"],
      "exclude_traits": ["experimental"]
    }
  }
}

Field Details:

  • name (string, required): Team name
  • description (string, optional): Team description
  • agents (array[object], default: []): Agent configurations
    • name (string, required): Agent name
    • description (string, optional)
    • system_prompt (string, optional): Agent instructions
    • model (string, required): LLM model
    • temperature (float, default: 0.7)
    • max_tokens (integer, optional)
    • image_url (string, optional): Agent avatar/logo URL (stored in dedicated column)
    • publication (object, optional): Agent publication settings
      • access_level (string, required): public | private | password_protected
      • chat_uri (string, optional): Custom URI slug for public access
      • domain (string, optional): Domain name (must exist in account)
      • password (string, optional): Password for password_protected access (write-only)
    • configuration (object, optional): Additional configuration (JSON deep merge)
      • chat_ui (object, optional): Chat interface customization
        • empty_title (string, optional): Welcome screen title
        • empty_description (string, optional): Welcome screen description
        • greeting (string, optional): Chat greeting message
        • suggested_prompts (array[object], optional): Starter prompts (max 8)
          • icon (string, optional): Iconify icon name (e.g., i-heroicons-light-bulb)
          • title (string, required): Prompt title
          • text (string, required): Full prompt text
    • events (array[object], default: []): Event listeners
    • traits (array[string], default: []): Trait identifiers
    • delegations (array[object], default: []): Delegation rules
  • tools (array[object], default: []): Tool configurations
    • name (string, required)
    • description (string, optional)
    • type (string, required): Tool type (mcp | external | function)
    • config (object, optional): Tool-specific configuration
  • knowledge (array[object], default: []): Knowledge source configurations
    • name (string, required)
    • description (string, optional)
    • type (string, required): Source type
    • source (string, required): Source path or URL
    • processing (object, optional): Processing configuration
  • traits (array[object], default: []): Trait definitions
    • name (string, required)
    • category (string, optional)
    • description (string, optional)
    • tags (array[string], default: [])
  • overrides (object, optional): Global and agent-specific overrides
  • filters (object, optional): Component inclusion/exclusion filters

Field Mapping & Storage ​

Agent fields are stored in two ways:

FieldStorage LocationBehavior
image_urlDedicated Agent.image_url column (String)Full replacement - new value overwrites existing
configuration.chat_ui.*Agent.configuration JSON column (deep merge)Deep merge - updates preserve other fields
publication.*Dedicated columns (access_level, chat_uri, domain, password_hash)Full replacement per field

Deep Merge Behavior (configuration.chat_ui):

The API performs a deep merge when updating configuration.chat_ui:

  • Updating one field preserves all others:

    json
    // Existing: {"chat_ui": {"empty_title": "Hello", "greeting": "Hi"}}
// Update: {"configuration": {"chat_ui": {"empty_title": "Welcome"}}}
// Result: {"chat_ui": {"empty_title": "Welcome", "greeting": "Hi"}}

  • Setting a field to null removes it:

    json
    // Update: {"configuration": {"chat_ui": {"greeting": null}}}
// Result: {"chat_ui": {"empty_title": "Welcome"}}

  • Omitting the entire block preserves existing values:

    json
    // Update: {"name": "New Name"}  (no configuration field)
// Result: configuration.chat_ui remains unchanged

Optional Field Preservation:

If optional fields are not provided in the push payload, existing values are preserved:

  • If image_url is not provided → existing value preserved
  • If publication is not provided → existing publication settings preserved
  • If configuration.chat_ui is not provided → existing chat UI configuration preserved

This is consistent with how other push fields work (events, delegations).

Response: Full team object

Errors:

  • 400: Invalid configuration or validation failed
  • 401: Authentication required
  • 403: Master API key cannot create teams (use account-specific API key or JWT)

Example:

bash
curl -X POST "https://api.gnosari.com/api/v1/teams/push" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @team-config.json

GET /teams/{identifier}/pull ​

Get comprehensive team configuration as JSON.

Pull operations export complete team configurations in the same format accepted by push operations. This allows you to:

  • Export existing teams to version control
  • Create team templates
  • Migrate teams between accounts
  • Document team configurations

Authentication: Required (JWT or API Key)

Path Parameters:

  • identifier (string): Team identifier

Response: Complete team configuration (same format as POST /teams/push request body)

json
{
  "name": "AI Development Team",
  "description": "Multi-agent team for software development tasks",
  "agents": [
    {
      "name": "code_reviewer",
      "description": "Reviews code for quality and best practices",
      "system_prompt": "You are an expert code reviewer.",
      "model": "claude-3-5-sonnet-20241022",
      "temperature": 0.1,
      "max_tokens": 4000,
      "events": [...],
      "traits": [...],
      "delegations": [...]
    }
  ],
  "tools": [...],
  "knowledge": [...],
  "traits": [...],
  "overrides": {...},
  "filters": {...}
}

Errors:

  • 401: Authentication required
  • 403: Insufficient permissions
  • 404: Team not found
  • 500: Failed to convert team to configuration

Example:

bash
curl -X GET "https://api.gnosari.com/api/v1/teams/sales-team/pull" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" > team-config.json

Push/Pull Workflow ​

The push/pull pattern enables infrastructure-as-code workflows for team management:

1. Pull existing team configuration:

bash
curl -X GET "https://api.gnosari.com/api/v1/teams/my-team/pull" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" > team.json

2. Edit configuration (version control, code review, etc.):

bash
git add team.json
git commit -m "Update team configuration"

3. Push updated configuration:

bash
curl -X POST "https://api.gnosari.com/api/v1/teams/push" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @team.json

This workflow allows you to manage teams as code, apply version control, perform code reviews, and automate deployments.