Sarj AI Developer API Integrations API

openapi: 3.2.0
info:
  title: Sarj Ai Developer Integrations API
  version: 1.0.0
  description: 'Operations tagged integrations across 2 of this provider''s published API definitions: sarj-ai-developer-api-voice-platform-openapi.json, sarj-ai-developer-api-integrations-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://platform-api.sarj.ai/api/v1
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Integrations
paths:
  /v1/beta/integrations/active-providers:
    get:
      tags:
      - Integrations
      summary: List Active Providers
      operationId: integrationsListActiveProviders
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ProviderItem'
                type: array
                title: Response Integrationslistactiveproviders
  /v1/beta/integrations/token/{provider}:
    get:
      tags:
      - Integrations
      summary: Get Token
      operationId: integrationsGetToken
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IntegrationProvider'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Integrations
      summary: Delete Token
      operationId: integrationsDeleteToken
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IntegrationProvider'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/token:
    post:
      tags:
      - Integrations
      summary: Add Token
      operationId: integrationsAddToken
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Data
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/token/refresh-all:
    post:
      tags:
      - Integrations
      summary: Refresh All
      description: 'Refresh only OAuth tokens; providers without a token refresher count as failures.


        Returns:

        Per-provider and total success/failure counts for the refresh sweep.'
      operationId: integrationsRefreshAll
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshAllTokensResponse'
  /v1/beta/integrations/zoho/create-webhook:
    servers:
    - url: https://platform-api.sarj.ai/api/v1
      description: Base URL declared by the provider in apis.yml (roadmap#122).
    post:
      tags:
      - Integrations
      summary: Create Notification
      operationId: integrationsCreateNotification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZohoWebhookData'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoNotificationCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    IntegrationProvider:
      type: string
      enum:
      - zoho
      - salla
      - salesforce
      title: IntegrationProvider
      description: "Available integration providers.\n\n`salla-tools` and `zoho-desk-create-ticket` require external OAuth setup and are\nNEVER auto-generated in the output tool config, connected or not - suggest them\ninstead (see `Suggestion Categorization for Integration Tools` below).\n\n**Suggestion Categorization for Integration Tools:**\n\n   **Use `verification_needed`** (shows in \"Action Required\" section):\n   - When user EXPLICITLY mentions needing Salla/Zoho in their business requirements\n   - Example: User says \"We use Salla for orders\" but Salla not in active integrations\n   - This is a REQUIREMENT the user stated - they need to set it up\n\n   **Use `resource_linking`** (shows in \"Opportunities\" section):\n   - When LLM SUGGESTS an integration that could enhance the scenario\n   - User did NOT ask for this; LLM thinks it would be helpful\n   - Example: For a restaurant scenario, LLM suggests Salla could help with order tracking\n\n**Examples:**\n\nUser prompt: \"We need Salla for order management\"\nActive integrations: None connected\n→ DO NOT add a salla-tools entry to the tool config\n→ ADD `verification_needed` suggestion: \"Connect Salla Store\" with action_url=\"/integrations\"\n\nUser prompt: \"Restaurant delivery agent\" (no mention of Salla/Zoho)\nActive integrations: zoho\n→ DO NOT add a zoho-desk-create-ticket entry to the tool config\n→ Can suggest salla as `resource_linking` (optional enhancement)"
    AuthType:
      type: string
      enum:
      - oauth
      - api_key
      title: AuthType
    RefreshAllTokensResponse:
      properties:
        provider_stats:
          additionalProperties:
            additionalProperties:
              type: integer
            type: object
          type: object
          title: Provider Stats
        total_success:
          type: integer
          title: Total Success
          default: 0
        total_fail:
          type: integer
          title: Total Fail
          default: 0
      type: object
      title: RefreshAllTokensResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CredentialPublic:
      properties:
        id:
          type: string
          title: Id
        organization_id:
          type: string
          title: Organization Id
        provider:
          $ref: '#/components/schemas/IntegrationProvider'
        auth_type:
          $ref: '#/components/schemas/AuthType'
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - organization_id
      - provider
      - auth_type
      - expires_at
      - scopes
      - metadata
      - created_at
      - updated_at
      title: CredentialPublic
    ProviderItem:
      properties:
        provider:
          $ref: '#/components/schemas/IntegrationProvider'
      type: object
      required:
      - provider
      title: ProviderItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ZohoNotificationCreateResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_NotificationResponseCreate'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationCreateResponse
    _NotificationResponseCreate:
      properties:
        code:
          type: string
          const: SUCCESS
          title: Code
        details:
          $ref: '#/components/schemas/_NotificationDetails'
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - details
      - message
      title: _NotificationResponseCreate
    ZohoWebhookData:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ZohoNotificationEvent'
          type: array
          title: Events
        query_params:
          $ref: '#/components/schemas/ZohoWebhookQueryParams'
        extra_conditions:
          anyOf:
          - $ref: '#/components/schemas/EventEvaluationConditions'
          - type: 'null'
          description: Extra conditions that may be injected in the webhook configuration. Allows fine-tuning routing different cases to scenarios.
      type: object
      required:
      - events
      - query_params
      title: ZohoWebhookData
      description: Required payload to create a new Zoho webhook
    _NotificationDetails:
      properties:
        events:
          items:
            $ref: '#/components/schemas/_NotificationEvent'
          type: array
          title: Events
      type: object
      required:
      - events
      title: _NotificationDetails
    _NotificationEvent:
      properties:
        channel_expiry:
          type: string
          format: date-time
          title: Channel Expiry
        resource_uri:
          type: string
          title: Resource Uri
        resource_id:
          type: string
          title: Resource Id
        resource_name:
          type: string
          title: Resource Name
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - channel_expiry
      - resource_uri
      - resource_id
      - resource_name
      - channel_id
      title: _NotificationEvent
    ZohoWebhookQueryParams:
      properties:
        scenario_id:
          type: string
          title: Scenario Id
        user_email:
          type: string
          title: User Email
        user_id:
          type: string
          title: User Id
        organization_id:
          type: string
          title: Organization Id
        trunk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Id
        language:
          $ref: '#/components/schemas/Language'
          default: ar
      type: object
      required:
      - scenario_id
      - user_email
      - user_id
      - organization_id
      title: ZohoWebhookQueryParams
      description: The query params retrieved from Zoho webhooks
    EqualityCondition:
      properties:
        condition_type:
          type: string
          const: equality
          title: Condition Type
          default: equality
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
        expected_field_value:
          type: string
          minLength: 1
          title: Expected Field Value
      type: object
      required:
      - evaluated_field_name
      - expected_field_value
      title: EqualityCondition
    Language:
      type: string
      enum:
      - en
      - ar
      - ur
      title: Language
      description: Language codes in ISO 639-1
    ZohoCRMModules:
      type: string
      enum:
      - Leads
      - Contacts
      - Calls
      title: ZohoCRMModules
    ZohoNotificationEvent:
      type: string
      enum:
      - Leads.create
      - Leads.edit
      - Contacts.create
      - Contacts.edit
      title: ZohoNotificationEvent
    EventEvaluationConditions:
      properties:
        module_type:
          $ref: '#/components/schemas/ZohoCRMModules'
        conditions:
          items:
            oneOf:
            - $ref: '#/components/schemas/EqualityCondition'
            - $ref: '#/components/schemas/LikenessCondition'
            - $ref: '#/components/schemas/EmptyCondition'
            discriminator:
              propertyName: condition_type
              mapping:
                empty: '#/components/schemas/EmptyCondition'
                equality: '#/components/schemas/EqualityCondition'
                likeness: '#/components/schemas/LikenessCondition'
          type: array
          minItems: 1
          title: Conditions
      type: object
      required:
      - module_type
      - conditions
      title: EventEvaluationConditions
    LikenessCondition:
      properties:
        condition_type:
          type: string
          const: likeness
          title: Condition Type
          default: likeness
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
        expected_field_value:
          type: string
          minLength: 1
          title: Expected Field Value
      type: object
      required:
      - evaluated_field_name
      - expected_field_value
      title: LikenessCondition
    EmptyCondition:
      properties:
        condition_type:
          type: string
          const: empty
          title: Condition Type
          default: empty
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
      type: object
      required:
      - evaluated_field_name
      title: EmptyCondition
x-refined-from:
- sarj-ai-developer-api-voice-platform-openapi.json
- sarj-ai-developer-api-integrations-api-openapi.yml