Universal Connector Schemas API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The universal connector schemas API manages custom data collection schemas. Schemas define the structure of data that universal connectors collect from external systems using sandboxed Python scripts.

Why it matters: Developers creating custom collectors need to define schemas that describe the entity types, fields, and relationships that the collector will discover.

Endpoints

Method	Path	Description	Auth required
GET	/internal/v1/connector/universal/schemas	List all schemas	JWT + API token
GET	/internal/v1/connector/universal/schemas/:id	Get schema details	JWT + API token
GET	/internal/v1/connector/universal/schemas/:id/history	Get schema change history	JWT + API token
POST	/internal/v1/connector/universal/schemas	Create a new schema	JWT + API token
PUT	/internal/v1/connector/universal/schemas/:id	Update a schema	JWT + API token
DELETE	/internal/v1/connector/universal/schemas/:cid/:id	Delete a schema	JWT + API token
DELETE	/internal/v1/connector/universal/schemas/:cid/:id/erase	Erase schema and data	JWT + API token
GET	/internal/v1/connector/universal/generate/schema-id/:connector/:id	Generate schema ID	JWT + API token
GET	/internal/v1/connector/universal/generate/schema-uuid/:connector/:id	Generate schema UUID	JWT + API token
GET	/internal/v1/connector/universal/model/schemas	Get model schema definitions	JWT + API token

Documentation & Tools

Method	Path	Description	Auth required
GET	/internal/v1/connector/universal/docs	List connector documentation	JWT + API token
GET	/internal/v1/connector/universal/docs/:id	Get specific documentation	JWT + API token
GET	/internal/v1/connector/universal/tools/:connectorid	List connector tools	JWT + API token
POST	/internal/v1/connector/universal/action/:connectorid/:actionId	Execute connector action	JWT + API token

---

POST /internal/v1/connector/universal/schemas

Create a new universal connector schema.

Request:

POST /internal/v1/connector/universal/schemas
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Custom REST API",
  "connectorId": "connector-uuid",
  "entityType": "account",
  "fields": [
    { "name": "userId", "type": "string", "primary": true },
    { "name": "username", "type": "string" },
    { "name": "email", "type": "string" },
    { "name": "role", "type": "string" },
    { "name": "active", "type": "boolean" }
  ]
}

Response (201):

{
  "id": "schema-uuid-001",
  "name": "Custom REST API",
  "status": "created",
  "version": 1
}

---

GET /internal/v1/connector/universal/schemas/:id/history

Get the change history for a schema. Use this to track modifications over time.

Request:

GET /internal/v1/connector/universal/schemas/schema-uuid-001/history
Authorization: Bearer <token>

Response (200):

{
  "history": [
    {
      "version": 2,
      "changedAt": "2026-02-12T10:00:00Z",
      "changedBy": "admin@example.com",
      "changes": ["Added field: department"]
    },
    {
      "version": 1,
      "changedAt": "2026-02-01T10:00:00Z",
      "changedBy": "admin@example.com",
      "changes": ["Initial creation"]
    }
  ]
}

---

DELETE /internal/v1/connector/universal/schemas/:cid/:id/erase

Delete a schema and erase all collected data associated with it. This is a destructive operation.

Path parameters:

Parameter	Type	Description
cid	string	Connector ID
id	string	Schema ID

Request:

DELETE /internal/v1/connector/universal/schemas/connector-uuid/schema-uuid-001/erase
Authorization: Bearer <token>

Response (204): No content.

DANGER

This operation permanently deletes the schema and all associated collected data. This cannot be undone.