# Configuration schema

JSON Schemas for the agent configuration change set (sections, fields, limits and allowed values).

|  |  |
| --- | --- |
| REST | `GET /api/v1/schema/configuration` |
| MCP tool | `get_configuration_schema` |
| Classification | **Read** (changes nothing) |
| Scope | Any valid token |
| Minimum role on the agent | any member |
| Confirmation | Not needed |
| Retry safety | Safe to retry with the same input |
| Success status | 200 |

## What it does

JSON Schemas for the agent configuration change set (sections, fields, limits and allowed values). Read it before writing changes.

## Side effects

None. It only reads.

## Inputs

No inputs.

## Example

REST:

```bash
curl "https://covo.lanaai.io/api/v1/schema/configuration" \
  -H "Authorization: Bearer $COVO_TOKEN"
```

MCP (POST /mcp):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_configuration_schema",
    "arguments": {}
  }
}
```

## Response

Returns an object with `change_set`. This is a real response, shortened to two items per list.

200 response:

```json
{
  "change_set": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "identity": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "represents": {
            "type": "string",
            "enum": [
              "individual",
              "creator"
            ]
          },
          "headline": {
            "type": "string",
            "maxLength": 80
          },
          "short_bio": {
            "type": "string",
            "maxLength": 300
          },
          "long_bio": {
            "type": "string",
            "maxLength": 3000
          },
          "avatar_url": {
            "anyOf": [
              "{...}",
              "{...}"
            ]
          },
          "location": {
            "type": "string",
            "maxLength": 80
          },
          "occupation": {
            "type": "string",
            "maxLength": 80
          },
          "expertise": {
            "default": [],
            "maxItems": 30,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          "interests": {
            "default": [],
            "maxItems": 30,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          "contact_email": {
            "anyOf": [
              "{...}",
              "{...}"
            ]
          },
          "contact_preferences": {
            "type": "string",
            "maxLength": 300
          }
        },
        "additionalProperties": false
      },
      "personality": {
        "type": "object",
        "properties": {
          "agent_name": {
            "type": "string",
            "maxLength": 40
          },
          "assistant_label": {
            "type": "string",
            "enum": [
              "AI Concierge",
              "AI Assistant"
            ]
          },
          "greeting": {
            "type": "string",
            "maxLength": 300
          },
          "tone": {
            "type": "string",
            "maxLength": 160
          },
          "instructions": {
            "type": "string",
            "maxLength": 4000
          },
          "boundaries": {
            "type": "string",
            "maxLength": 1000
          },
          "prohibited_topics": {
            "maxItems": 30,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          "fallback_behavior": {
            "type": "string",
            "enum": [
              "offer_contact",
              "offer_links"
            ]
          },
          "lead_capture_mode": {
            "type": "string",
            "enum": [
              "off",
              "conservative"
            ]
          },
          "suggested_prompts": {
            "maxItems": 8,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          }
        },
        "additionalProperties": false
      },
      "links": {
        "type": "object",
        "properties": {
          "add": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "title",
                "url"
              ],
              "additionalProperties": false
            }
          },
          "update": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          },
          "remove": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "additionalProperties": false
      },
      "offers": {
        "type": "object",
        "properties": {
          "add": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "kind",
                "title"
              ],
              "additionalProperties": false
            }
          },
          "update": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          },
          "remove": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "additionalProperties": false
      },
      "knowledge": {
        "type": "object",
        "properties": {
          "add": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "title",
                "content"
              ],
              "additionalProperties": false
            }
          },
          "update": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          },
          "remove": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "additionalProperties": false
      },
      "places": {
        "type": "object",
        "properties": {
          "add": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "kind",
                "name"
              ],
              "additionalProperties": false
            }
          },
          "update": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": "{...}",
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          },
          "remove": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  }
}
```

Over MCP the same object comes back as the tool result, in `structuredContent` and as JSON text.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect. |
| 403 | `account_suspended` | The account that owns the token is paused. |
| 400 | `bad_request` | An input is invalid; `field` names it. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |