Skip to main content
Third-party integrations bundle a set of tools + required credentials. Wrapped by the Python SDK and Node SDK.

​
Endpoints at a glance

MethodPathSummary
GET/api/v1/integrationsList third-party integrations
GET/api/v1/integrations/{id}Get a single integration
POST/api/v1/integrations/{id}/installInstall an integration
POST/api/v1/integrations/{id}/uninstallUninstall an integration
GET/api/v1/mcp-connectionsList MCP connections (stub)
GET/api/v1/native-toolsList native tools (stub)

​
Reference

​
GET /api/v1/integrations

List third-party integrations Returns the catalog of third-party integrations (Stripe, Shopify, …) for this tenant. Includes per-category counts. Parameters
NameInTypeRequiredDescription
categoryquerystringNoFilter by category
statusquerystringNoFilter by install status (available, installed)
Responses
CodeDescriptionBody
200OKobject
400Missing X-Account-ID headerstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/integrations \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
GET /api/v1/integrations/{id}

Get a single integration Parameters
NameInTypeRequiredDescription
idpathstringYesIntegration id (uuid) or snake_case name
Responses
CodeDescriptionBody
200OKhandlers.ThirdPartyIntegration
404Integration not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/integrations/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/integrations/{id}/install

Install an integration Stores params (plaintext) and secrets (encrypted) supplied by the caller, then flips the integration row’s status to ‘installed’. Empty body installs without params. Parameters
NameInTypeRequiredDescription
idpathstringYesIntegration id (uuid) or name
Request body (application/json) Schema: handlers.InstallIntegrationRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
paramsobjecte.g. {'api_version': '2024-09', 'region': 'us-east-1'}
secretsobjecte.g. {'api_key': 'sk_live_...', 'webhook_secret': 'whsec_...'}
Responses
CodeDescriptionBody
200OKobject
404Integration not foundstring
500Database errorstring
503Secret encryption service unavailablestring
Example 
curl https://api.kataven.ai/v1/integrations/agent_01HZ2N.../install \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "api_version": "2024-09",
    "region": "us-east-1"
  },
  "secrets": {
    "api_key": "sk_live_...",
    "webhook_secret": "whsec_..."
  }
}'

​
POST /api/v1/integrations/{id}/uninstall

Uninstall an integration Flips status back to ‘available’ and clears installed_at. Stored params/secrets are NOT purged. Parameters
NameInTypeRequiredDescription
idpathstringYesIntegration id (uuid) or name
Responses
CodeDescriptionBody
200OKobject
404Integration not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/integrations/agent_01HZ2N.../uninstall \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
GET /api/v1/mcp-connections

List MCP connections (stub) Returns an empty list — endpoint reserved for future use. Responses
CodeDescriptionBody
200OKobject
400Missing X-Account-ID headerstring
Example 
curl https://api.kataven.ai/v1/mcp-connections \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
GET /api/v1/native-tools

List native tools (stub) Returns an empty list — endpoint reserved for future use. Responses
CodeDescriptionBody
200OKobject
400Missing X-Account-ID headerstring
Example 
curl https://api.kataven.ai/v1/native-tools \
  -H "Authorization: Bearer $KATAVEN_API_KEY"