Chat Schemas API

Define reusable JSON Schemas for a project's AI chat workflows.

These schemas are used to validate structured extraction data and power trigger criteria/actions downstream.

Endpoints

GET    /api/organizations/{organizationId}/projects/{projectId}/chat-schemas
POST   /api/organizations/{organizationId}/projects/{projectId}/chat-schemas
GET    /api/organizations/{organizationId}/projects/{projectId}/chat-schemas/{schemaId}
PATCH  /api/organizations/{organizationId}/projects/{projectId}/chat-schemas/{schemaId}
DELETE /api/organizations/{organizationId}/projects/{projectId}/chat-schemas/{schemaId}

Authentication and Authorization

These endpoints are organization-scoped and support:

• authenticated dashboard session, or
• project API key with chat_schemas:read / chat_schemas:write (or project:admin)

Every request is checked for one of:

1. Logged-in user (401 if missing)
2. Organization membership (403 if user is not in org)
3. Project ownership (404 if project does not belong to org)

Create Schema

POST /chat-schemas

Request Body

Field	Type	Required	Description
name	string	yes	Schema display name
description	string | null	no	Optional description
schemaVersion	integer	no	Defaults to 1
schema	object	yes	JSON Schema object

Example

{
  "name": "Lead Intake v1",
  "description": "Collect lead and case context",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "additionalProperties": false,
    "required": ["name"],
    "properties": {
      "name": { "type": "string", "minLength": 1 },
      "email": { "type": "string", "format": "email" },
      "phone": { "type": "string" },
      "caseType": { "type": "string" }
    }
  }
}

Update Schema

PATCH /chat-schemas/{schemaId}

Send any subset of:

• name
• description
• schema
• schemaVersion

If schema is changed and schemaVersion is omitted, Syntropy auto-increments the version.

Schema Validation Rules

Syntropy validates the submitted JSON Schema with AJV before persistence.

• Invalid schemas return 400
• External $ref values are blocked
• Internal refs (for example #/definitions/MyType) are allowed

Responses

Success

{
  "schema": {
    "id": "uuid",
    "name": "Lead Intake v1",
    "description": "Collect lead and case context",
    "schemaVersion": 1,
    "schema": { "...": "..." },
    "createdAt": "2026-02-19T00:00:00.000Z",
    "updatedAt": "2026-02-19T00:00:00.000Z"
  }
}

Validation Error

{
  "error": "Invalid JSON schema: ..."
}

Example cURL

curl -X POST \
  "https://syntropy.chat/api/organizations/{orgId}/projects/{projectId}/chat-schemas" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer syn_sk_xxx" \
  -d '{
    "name": "Lead Intake v1",
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      }
    }
  }'

Example: SDK API Client

import { createSyntropyApiClient } from "@eclosion-tech/syntropy-node";

const api = createSyntropyApiClient({
  baseUrl: "https://syntropy.chat/api",
  apiKey: process.env.SYNTROPY_API_KEY,
});

const scope = { organizationId: "org_uuid", projectId: "project_uuid" };

await api.chatSchemas.create(scope, {
  name: "Lead Intake v1",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
    },
  },
});

const { schemas } = await api.chatSchemas.list(scope);