PlatformIntegration

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ada/main/json-schema/ada-platform-integration-schema.json",
  "title": "PlatformIntegration",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ada-platformintegrations-api-openapi.yml#/components/schemas/PlatformIntegration",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique identifier for the integration"
    },
    "status": {
      "type": "string",
      "description": "The current state of the integration (development, approved, archived)"
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "description": "The date the integration was created"
    },
    "updated": {
      "type": "string",
      "format": "date-time",
      "description": "The date the integration was last updated"
    },
    "identifier_field_path": {
      "$ref": "#/$defs/IntegrationIdentifierField"
    },
    "icon_url": {
      "$ref": "#/$defs/IntegrationIconUrl"
    },
    "call_to_action": {
      "$ref": "#/$defs/IntegrationCallToAction"
    },
    "name": {
      "type": "string",
      "description": "The name of the integration"
    },
    "description": {
      "type": "string",
      "description": "A description of what the integration does and how to use it"
    },
    "author": {
      "type": "string",
      "description": "The name of the integration developer"
    },
    "contact": {
      "type": "string",
      "description": "The URL or email address where users of the integration can reach out for support"
    },
    "uninstallation_url": {
      "type": "string",
      "format": "url",
      "description": "The `delete` endpoint that initiates the uninstallation flow for the integration"
    },
    "oauth_callback_url": {
      "type": "string",
      "format": "url",
      "description": "The `get` endpoint that will be invoked after OAuth authorization"
    },
    "tags": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PlatformIntegrationTagsItems"
      },
      "description": "A list of tags that describe the type of integration"
    },
    "error_codes": {
      "oneOf": [
        {
          "$ref": "#/$defs/PlatformIntegrationErrorCodes"
        },
        {
          "type": "null"
        }
      ],
      "description": "An object containing error codes and their corresponding error message the integration may return to the OAuth failure page to be displayed"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The list of OAuth token permissions the integration requests when installed"
    },
    "configuration_fields": {
      "$ref": "#/$defs/PlatformIntegrationConfigurationFields",
      "description": "A json-schema describing the settings fields that a user should be presented with when installing the integration"
    }
  },
  "required": [
    "id",
    "status",
    "identifier_field_path",
    "name",
    "description",
    "author",
    "contact",
    "uninstallation_url",
    "oauth_callback_url",
    "tags",
    "scopes",
    "configuration_fields"
  ],
  "$defs": {
    "IntegrationCallToAction": {
      "type": [
        "string",
        "null"
      ],
      "description": "The call to action text",
      "title": "IntegrationCallToAction"
    },
    "IntegrationIconUrl": {
      "type": [
        "string",
        "null"
      ],
      "format": "url",
      "description": "The URL of the icon that should be displayed with your integration",
      "title": "IntegrationIconUrl"
    },
    "IntegrationIdentifierField": {
      "type": "string",
      "description": "JMESPath describing which of the fields in `configuration_fields` is the best human-friendly field to use to identify a specific installation (e.g., account name)",
      "title": "IntegrationIdentifierField"
    },
    "PlatformIntegrationConfigurationFields": {
      "type": "object",
      "properties": {},
      "description": "A json-schema describing the settings fields that a user should be presented with when installing the integration",
      "title": "PlatformIntegrationConfigurationFields"
    },
    "PlatformIntegrationErrorCodes": {
      "type": "object",
      "properties": {},
      "description": "An object containing error codes and their corresponding error message the integration may return to the OAuth failure page to be displayed",
      "title": "PlatformIntegrationErrorCodes"
    },
    "PlatformIntegrationTagsItems": {
      "type": "string",
      "enum": [
        "knowledge"
      ],
      "title": "PlatformIntegrationTagsItems"
    }
  }
}