Schema API Reference

Overview

OpenOBA connects to any enterprise system through standard REST APIs. Regardless of your existing system's language or architecture, implementing these interfaces lets OpenOBA's Agent operate your system using natural language.

Authentication

All API requests require an API Key in the Header:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Generate and manage API Keys in the Admin Console under System Configuration → API Keys.

Standard Endpoints

Method	Path	Description
GET	/api/external/:entity	Query entity list (supports pagination, filtering, sorting)
GET	/api/external/:entity/:id	Get single entity detail
POST	/api/external/:entity	Create entity
PUT	/api/external/:entity/:id	Update entity
DELETE	/api/external/:entity/:id	Delete entity (soft delete)
GET	/api/external/:entity/count	Count entities
POST	/api/external/:entity/sync	Batch sync data

Detailed Reference

Query List

GET /api/external/products?page=1&limit=20&sort=createdAt&order=desc&filter[name]=glasses

Parameter	Type	Description
page	number	Page number, default 1
limit	number	Items per page, default 20, max 100
sort	string	Sort field
order	string	Sort direction (asc / desc)
filter[field]	string	Fuzzy filter by field

Create Entity

POST /api/external/products
Content-Type: application/json

{
  "name": "Classic Round Glasses",
  "price": 299.00,
  "category": "EYEWEAR",
  "colorCode": "BK-001"
}

Batch Sync

POST /api/external/products/sync
Content-Type: application/json

{
  "mode": "upsert",
  "keyField": "externalId",
  "items": [
    { "externalId": "EXT-001", "name": "Product A", "price": 199 },
    { "externalId": "EXT-002", "name": "Product B", "price": 299 }
  ]
}

Response Format

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "limit": 20, "total": 156, "totalPages": 8 },
  "timestamp": "2026-06-30T08:00:00.000Z"
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'price' is required",
    "details": [{ "field": "price", "reason": "required" }]
  }
}

Entity Discovery

GET /api/external/entities

# Response
{
  "success": true,
  "data": {
    "Product": {
      "fields": {
        "name": { "type": "String", "required": true },
        "price": { "type": "Float", "required": true },
        "category": { "type": "String", "required": true, "enum": ["EYEWEAR", ...] }
      },
      "aliases": { "selling price": "retailPrice", "item code": "productCode" },
      "actions": ["create", "update", "remove", ...]
    }
  }
}

The Agent auto-discovers your system structure through this endpoint—no manual instruction needed.

Integrating Existing Systems

Scenario 1: You Have Source Code

Add the above API endpoints to your backend. Each endpoint calls your existing business logic. Estimated effort: 2-4 person-days.

Scenario 2: No Source Code (Legacy / COTS)

Build a lightweight Adapter Service (~200 lines of code) around your legacy system. It exposes the standard API externally while connecting to your legacy system internally via database or HTTP. Or use OpenOBA to rapidly rebuild your system.