API Schema

API Schema

Give your AI assistant the ability to execute real API calls on behalf of the user. By providing an OpenAPI/Swagger schema, the AI can understand your backend and take actions — creating orders, fetching data, updating settings, and more.

How It Works

  1. You provide an OpenAPI schema (URL or inline object)
  2. The SDK loads and summarizes the available endpoints
  3. When a user asks for something that requires an API call, the AI identifies the right endpoint
  4. The SDK executes the call (client-side or via server proxy) and returns the result
User: "Cancel my subscription"
  → AI reads API schema
  → Finds: DELETE /api/subscriptions/{id}
  → SDK executes the call
  → AI confirms: "Your subscription has been cancelled."

Configuration

React

import { ProduckProvider, ProduckChat } from '@prodact.ai/sdk/react'
 
function App() {
  return (
    <ProduckProvider
      sdkKey="pk_live_..."
      apiSchema="/api/openapi.json"
      apiAuth={{ type: 'cookie' }}
      allowedEndpoints={[
        'GET /api/users/*',
        'POST /api/orders',
        'DELETE /api/subscriptions/*',
      ]}
    >
      <ProduckChat />
    </ProduckProvider>
  )
}

Vanilla JavaScript

Produck.init({
  sdkKey: 'pk_live_...',
  apiSchema: '/api/openapi.json',
  apiAuth: { type: 'cookie' },
  allowedEndpoints: [
    'GET /api/users/*',
    'POST /api/orders',
    'DELETE /api/subscriptions/*',
  ],
})

Schema Formats

URL (Recommended)

Point to your OpenAPI/Swagger endpoint:

apiSchema="/api/openapi.json"

The SDK fetches and parses the schema on initialization.

Inline Object

Provide the schema directly:

apiSchema={{
  openapi: '3.0.0',
  paths: {
    '/api/users/{id}': {
      get: {
        summary: 'Get user profile',
        parameters: [{ name: 'id', in: 'path', required: true }],
      },
    },
  },
}}

Authentication

Configure how API calls are authenticated:

Cookie Authentication (Default)

apiAuth={{ type: 'cookie' }}

The browser's existing cookies are sent with each request. Best for same-origin APIs where the user is already logged in.

Bearer Token

apiAuth={{ type: 'bearer', token: 'eyJhbG...' }}

An Authorization: Bearer <token> header is added to each request.

API Key

apiAuth={{
  type: 'api-key',
  key: 'X-API-Key',
  value: 'your-api-key',
}}

A custom header is added to each request.

Endpoint Whitelisting

Security is critical. The allowedEndpoints array controls exactly which endpoints the AI can call. If an endpoint isn't in the whitelist, it will be blocked.

allowedEndpoints={[
  'GET /api/users/*',       // Wildcard: any GET under /api/users/
  'POST /api/orders',       // Exact match
  'DELETE /api/subscriptions/*',
]}

Pattern Matching

PatternMatchesDoesn't Match
GET /api/users/*GET /api/users/123POST /api/users/123
POST /api/ordersPOST /api/ordersPOST /api/orders/123
* /api/public/*Any method under /api/public//api/private/

⚠️ Never whitelist destructive endpoints (DELETE, PUT on critical resources) without careful consideration.

Execution Flow

Client-Side First

By default, the SDK attempts to execute API calls directly from the browser:

Browser → Your API → Response → SDK → AI

This works best for same-origin APIs where the user has existing session cookies.

Server Proxy Fallback

If a client-side call fails due to CORS, the SDK automatically retries via the Produck server proxy:

Browser → Produck Proxy → Your API → Response → Browser

The proxy only forwards requests to domains listed in your project's allowed_proxy_domains setting (configured in the dashboard).

Best Practices

  1. Start with read-only endpoints — GET is safest to begin with
  2. Use specific whitelists — avoid * /api/* wildcard patterns
  3. Test thoroughly — try the AI calling each endpoint before going live
  4. Log API calls — monitor the audit log in the dashboard
  5. Use cookie auth when possible — simplest and most secure for same-origin

Next Steps

Knowledge BaseDOM Context